On this page
@addTagHelper *, Webority.Ui.RazorValue and onChange
The picker is controlled: value holds a YYYY-MM month string, and onChange gives back the new one.
ISO: 2026-03
Min and max
Constrain the selectable months with min and max so a month outside the window cannot be picked.
States
Disable a field that cannot change now, and show an error beside a field that needs a month.
Sizes
Match the field height to the inputs beside it, using sm in dense forms and lg on sign-in.
Every option
Every value of every prop, one cell each.
value
value=""value="2026-03"onChange
onChange is React only, so Razor posts the YYYY-MM value under namemin / max: bounds
min="2026-02" (no max)max="2026-10" (no min)min and max togetherdisabled
disabled="false" (default)disabled="true"size
size="sm"size="md" (default)size="lg"size="xl"displayFormat
display-format="MMM yyyy" (default)display-format="MMMM yyyy"display-format="MM/yyyy"display-format="yyyy-MM"id
id="billing-month" sets the control id, no visible changeariaLabel
aria-label="Billing month" names the field when no label is shownlabel
label="Billing month"required
required="false" (default)required="true"helperText
helper-text="Pick the month the invoice covers"error
error="Pick a month"name
name="billingMonth" posts the YYYY-MM month, no visible changeoptional
optional="false" (default)optional="true"optionalLabel
optional-label="(optional)" (default)optional-label="Not needed"className
input-class="date-w-sm" sizes the controlfieldClassName
class="mb-3" adds classes to the field wrapperreadOnly
read-only="false" (default)read-only="true"loading
loading="false" (default)loading="true"defaultValue
defaultValue has no Razor attribute; value sets a controlled starthelp
help="Pick the month the invoice covers." adds an info tiphelpLabel
help-label="More information" (default)help-label="About this month"Guidance
What to do, and what to avoid.
Use it when
- Capturing a single calendar month: billing month, reporting period, expiry month.
- You need one consistent month picker across every browser and both surfaces.
- Restricting selection to a valid window with min / max.
Reach for something else when
- You need a full calendar date. → AppDatePicker
- You are capturing a start-and-end range of months or dates. → AppDateRangePicker
- The value is free text, not a month. → AppInput
- You are picking from a fixed list of labels. → AppSelect
Give the month a visible label
A visible label above the field. The user knows what the month is for before opening it.
Only a placeholder as the label, which vanishes the moment a month is picked.
Set min and max bounds
min / max stop invalid months at the source, so the user can only pick a real one.
No bounds, then reject the month after submit. Constrain up front instead.
Reference
Try every prop, read the full list, and check keyboard and screen reader behaviour.
21 props. The 5 most used come first.
Used on most screens 5 props
| Prop | Type | Default | Description |
|---|---|---|---|
| labeldefault - | string | - | The field label, shown above the control and used as its accessible name. |
| valuedefault - | string | - | The YYYY-MM month the field holds, such as 2026-03. |
| requireddefault false | bool | false | Marks the field required, with the required mark on the label. |
| helper-textdefault - | string | - | Helper text shown under the control. |
| errordefault - | string | - | An error message shown under the control. |
Less common 16 props
| Prop | Type | Default | Description |
|---|---|---|---|
| namedefault - | string | - | The form field name the YYYY-MM month posts under. |
| mindefault - | string | - | The earliest selectable month, as YYYY-MM. |
| maxdefault - | string | - | The latest selectable month, as YYYY-MM. |
| placeholderdefault Choose a month | string | Choose a month | Text shown in the field while no month is chosen. |
| optionaldefault false | bool | false | Ends the label with (optional) when the field is not required. Required wins when both are set. |
| disableddefault - | bool | - | Disables the control. |
| read-onlydefault false | bool | false | Shows the value but blocks editing. The value still posts. |
| loadingdefault false | bool | false | Shows a busy state and blocks input while data loads. |
| helpdefault - | string | - | Info-tip content shown beside the label. |
| optional-labeldefault (optional) | string | (optional) | Replaces the built-in English text, for other languages. |
| help-labeldefault More information | string | More information | The accessible name of the info-tip button. |
| sizedefault md | sm | md | lg | xl | md | Control height tier, matching AppInput: sm 35px, md 40px, lg 45px, xl 50px. |
| display-formatdefault MMM yyyy | string | MMM yyyy | How the chosen month reads in the field, from the tokens yyyy, MMMM, MMM and MM (for example MMMM yyyy). The posted value stays YYYY-MM. |
| aria-labeldefault - | string | - | Accessible name when there is no visible label. |
| iddefault - | string | - | The id of the control; a unique one is made when left out. |
| input-classdefault - | string | - | Extra classes on the control itself. The plain class attribute merges onto the field wrapper that holds the label, helper text and error instead. |
Screen reader
3 notes- The field label names the control through aria-label when it is a string, and ariaLabel overrides it.
- Helper text or error text is linked to the control with aria-describedby, and an error sets aria-invalid. A caller's aria-invalid takes its place.
- Required and disabled are set as native attributes on the control.
Do and avoid
2 pairsGive the month a visible label
A visible label above the field. The user knows what the month is for before opening it.
Only a placeholder as the label, which vanishes the moment a month is picked.
Set min and max bounds
min / max stop invalid months at the source, so the user can only pick a real one.
No bounds, then reject the month after submit. Constrain up front instead.