Skip to content
Razor catalogue

On this page

@addTagHelper *, Webority.Ui.Razor

Value and onChange

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

A controlled month field
AppMonthPicker captures a month and year with no day. The calendar opens on the months of the selected year: click the year to move between years, pick a month to set it and close. Arrow keys move by month, PageUp and PageDown move by year, Enter selects and Esc closes.

ISO: 2026-03

Show code
<app-month-picker label="Billing month" name="billingMonth" value="2026-03"></app-month-picker>
<p>ISO: 2026-03</p>

Min and max

Constrain the selectable months with min and max so a month outside the window cannot be picked.

Restrict to a valid window
Show code
<app-month-picker label="Billing month" name="billingMonthRange" value="2026-03" min="2026-02" max="2026-10"></app-month-picker>

States

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

Disabled and error
Pick a month
Show code
<app-month-picker label="Locked" name="stLocked" value="2026-03" disabled="true"></app-month-picker>
<app-month-picker label="Billing month" name="stError" error="Pick a month"></app-month-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-month-picker label="Small (sm)" name="dsSm" value="2026-03" size="FieldSize.Sm"></app-month-picker>
<app-month-picker label="Medium (default)" name="dsMd" value="2026-03"></app-month-picker>
<app-month-picker label="Large (lg)" name="dsLg" value="2026-03" size="FieldSize.Lg"></app-month-picker>
<app-month-picker label="Extra large (xl)" name="dsXl" value="2026-03" size="FieldSize.Xl"></app-month-picker>

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 name

min / max: bounds

min="2026-02" (no max)
max="2026-10" (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="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 change

ariaLabel

aria-label="Billing month" names the field when no label is shown

label

label="Billing month"

required

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

helperText

helper-text="Pick the month the invoice covers"
Pick the month the invoice covers

error

error="Pick a month"
Pick a month

name

name="billingMonth" posts the YYYY-MM month, 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 month the invoice covers." adds an info tip

helpLabel

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

Do

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

Avoid

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

Set min and max bounds

Do

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

Avoid

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.

MMM yyyy MMMM yyyy MM/yyyy yyyy-MM
sm md lg xl
React, generated from the controls
<AppMonthPicker label="Billing month" name="pgMonth" value={value} onChange={setValue} />
Razor, the same props
<app-month-picker label="Billing month" name="pgMonth" />

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

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

Give the month a visible label

Do

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

Avoid

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

Set min and max bounds

Do

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

Avoid

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