On this page
@addTagHelper *, Webority.Ui.RazorValue and onChange
The picker is controlled: value holds a YYYY year string, and onChange gives back the new one.
Value: 2026
Min and max
Constrain the selectable years with min and max so a year outside the window cannot be picked.
States
Disable a field that cannot change now, and show an error beside a field that needs a year.
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"onChange
onChange is React only, so Razor posts the YYYY value under namemin / max: bounds
min="2024" (no max)max="2030" (no min)min and max togetherdisabled
disabled="false" (default)disabled="true"size
size="sm"size="md" (default)size="lg"size="xl"displayFormat
display-format="yyyy" (default)display-format="FY yyyy"id
id="financial-year" sets the control id, no visible changeariaLabel
aria-label="Financial year" names the field when no label is shownlabel
label="Financial year"required
required="false" (default)required="true"helperText
helper-text="Pick the year the figures cover"error
error="Pick a year"name
name="financialYear" posts the YYYY year, 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 year the figures cover." adds an info tiphelpLabel
help-label="More information" (default)help-label="About this year"Guidance
What to do, and what to avoid.
Use it when
- Capturing a single calendar year: financial year, reporting year, graduation year.
- You need one consistent year picker across every browser and both surfaces.
- Restricting selection to a valid window with min / max.
Reach for something else when
- You need a month or a full calendar date. → AppMonthPicker
- You are capturing a start-and-end range of dates. → AppDateRangePicker
- The value is free text, not a year. → AppInput
- You are picking from a fixed list of labels. → AppSelect
Give the year a visible label
A visible label above the field. The user knows what the year is for before opening it.
Only a placeholder as the label, which vanishes the moment a year is picked.
Set min and max bounds
min / max stop invalid years at the source, so the user can only pick a real one.
No bounds, then reject the year 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 year the field holds, such as 2026. |
| 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 year posts under. |
| mindefault - | string | - | The earliest selectable year, as YYYY. |
| maxdefault - | string | - | The latest selectable year, as YYYY. |
| placeholderdefault Choose a year | string | Choose a year | Text shown in the field while no year 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 yyyy | string | yyyy | How the chosen year reads in the field, from the token yyyy; any other text is kept as written (for example FY yyyy). The posted value stays YYYY. |
| 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 year a visible label
A visible label above the field. The user knows what the year is for before opening it.
Only a placeholder as the label, which vanishes the moment a year is picked.
Set min and max bounds
min / max stop invalid years at the source, so the user can only pick a real one.
No bounds, then reject the year after submit. Constrain up front instead.