Skip to content
Razor catalogue

On this page

@addTagHelper *, Webority.Ui.Razor

Value and onChange

The picker is controlled: value holds a YYYY year string, and onChange gives back the new one.

A controlled year field
AppYearPicker captures a year with no month or day. The calendar opens on the decade of the selected year: move between decades with the arrows, pick a year to set it and close. Arrow keys move by one year, Up and Down by three, PageUp and PageDown by ten years, Enter selects and Esc closes.

Value: 2026

Show code
<app-year-picker label="Financial year" name="financialYear" value="2026"></app-year-picker>
<p>Value: 2026</p>

Min and max

Constrain the selectable years with min and max so a year outside the window cannot be picked.

Restrict to a valid window
Show code
<app-year-picker label="Financial year" name="financialYearRange" value="2026" min="2024" max="2030"></app-year-picker>

States

Disable a field that cannot change now, and show an error beside a field that needs a year.

Disabled and error
Pick a year
Show code
<app-year-picker label="Locked" name="stLocked" value="2026" disabled="true"></app-year-picker>
<app-year-picker label="Financial year" name="stError" error="Pick a year"></app-year-picker>

Sizes

Match the field height to the inputs beside it, using sm in dense forms and lg on sign-in.

Four heights
Show code
<app-year-picker label="Small (sm)" name="dsSm" value="2026" size="FieldSize.Sm"></app-year-picker>
<app-year-picker label="Medium (default)" name="dsMd" value="2026"></app-year-picker>
<app-year-picker label="Large (lg)" name="dsLg" value="2026" size="FieldSize.Lg"></app-year-picker>
<app-year-picker label="Extra large (xl)" name="dsXl" value="2026" size="FieldSize.Xl"></app-year-picker>

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 name

min / max: bounds

min="2024" (no max)
max="2030" (no min)
min and max together

disabled

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 change

ariaLabel

aria-label="Financial year" names the field when no label is shown

label

label="Financial year"

required

required="false" (default)
required="true"

helperText

helper-text="Pick the year the figures cover"
Pick the year the figures cover

error

error="Pick a year"
Pick a year

name

name="financialYear" posts the YYYY year, no visible change

optional

optional="false" (default)
optional="true"

optionalLabel

optional-label="(optional)" (default)
optional-label="Not needed"

className

input-class="date-w-sm" sizes the control

fieldClassName

class="mb-3" adds classes to the field wrapper

readOnly

read-only="false" (default)
read-only="true"

loading

loading="false" (default)
loading="true"

defaultValue

defaultValue has no Razor attribute; value sets a controlled start

help

help="Pick the year the figures cover." adds an info tip

helpLabel

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

Do

A visible label above the field. The user knows what the year is for before opening it.

Avoid

Only a placeholder as the label, which vanishes the moment a year is picked.

Set min and max bounds

Do

min / max stop invalid years at the source, so the user can only pick a real one.

Avoid

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.

yyyy FY yyyy
sm md lg xl
React, generated from the controls
<AppYearPicker label="Financial year" name="pgYear" value={value} onChange={setValue} />
Razor, the same props
<app-year-picker label="Financial year" name="pgYear" />

21 props. The 5 most used come first.

Used on most screens 5 props

PropTypeDefaultDescription
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

PropTypeDefaultDescription
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 pairs

Give the year a visible label

Do

A visible label above the field. The user knows what the year is for before opening it.

Avoid

Only a placeholder as the label, which vanishes the moment a year is picked.

Set min and max bounds

Do

min / max stop invalid years at the source, so the user can only pick a real one.

Avoid

No bounds, then reject the year after submit. Constrain up front instead.