Skip to content
Razor catalogue

On this page

@addTagHelper *, Webority.Ui.Razor

Value and onChange

The picker is controlled: value holds an ISO date string, and onChange gives back the new one.

A controlled date field
AppDatePicker is the one way to capture a date: a raw input of type date renders a different widget in every browser, so this gives one calendar everywhere. The calendar is fully keyboard driven. Click the month or year to jump to a month or year picker, arrow keys move by day, PageUp and PageDown move by month (Shift for a year), Home and End jump to the week edges, Enter selects and Esc closes. A Today shortcut sits in the footer.

ISO: 2026-07-10

Show code
<app-date-picker label="Assessment date" name="assessmentDate" value="2026-07-10"></app-date-picker>
<p>ISO: 2026-07-10</p>

Min and max

Constrain the selectable window with min and max so an invalid date cannot be picked.

Restrict to a valid window
Show code
<app-date-picker label="Reporting date" name="reportingDate" value="2026-07-15" min="2026-07-01" max="2026-07-31"></app-date-picker>

Placeholder

Use a placeholder to say what the empty field expects, beside a label rather than in place of one.

Custom empty-state text
Show code
<app-date-picker label="Due date" name="dueDate" placeholder="Pick a due date"></app-date-picker>

Week start

Start the week on the day your people plan around, such as Sunday for a retail calendar.

Start the week on Sunday
Show code
<app-date-picker label="Delivery date" name="deliveryDate" first-day="0"></app-date-picker>

Width

Size the field to the date it holds, since a date is short and does not need a full column.

Sizing the field
Show code
<app-date-picker label="Small (date-w-sm)" name="dwSm" value="2026-07-10" class="date-w-sm"></app-date-picker>
<app-date-picker label="Large (date-w-lg)" name="dwLg" value="2026-07-10" class="date-w-lg"></app-date-picker>
<app-date-picker label="Full (date-w-full)" name="dwFull" value="2026-07-10" class="date-w-full"></app-date-picker>

Sizes

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

Three heights
Show code
<app-date-picker label="Small (sm)" name="dsSm" value="2026-07-10" size="ControlSize.Sm"></app-date-picker>
<app-date-picker label="Medium (default)" name="dsMd" value="2026-07-10"></app-date-picker>
<app-date-picker label="Large (lg)" name="dsLg" value="2026-07-10" size="ControlSize.Lg"></app-date-picker>

States

Disable a field that cannot change now, and mark a field that must be filled as required.

Disabled, required, and error
Pick a date
Show code
<app-date-picker label="Locked" name="stLocked" value="2026-07-10" disabled="true"></app-date-picker>
<app-date-picker label="Assessment date" name="stRequired" required="true"></app-date-picker>
<app-date-picker label="Assessment date" name="stError" error="Pick a date"></app-date-picker>

Every option

Every value of every prop, one cell each.

value

value=""
value="2026-07-10"

onChange

onChange is React only, so Razor posts the ISO value under name

min / max: bounds

min="2026-07-01" (no max)
max="2026-07-31" (no min)
min and max together

placeholder

placeholder="Choose a date" (default)
placeholder="Pick a due date"

disabled

disabled="false" (default)
disabled="true"

size

size="sm"
size="md" (default)
size="lg"

firstDay: every weekday

first-day="0"
first-day="1" (default)
first-day="2"
first-day="3"
first-day="4"
first-day="5"
first-day="6"

displayFormat

display-format="dd-MMM-yyyy" (default)
display-format="dd/MM/yyyy"
display-format="d MMMM yyyy"
display-format="yyyy-MM-dd"

id

id="assessment-date" sets the control id, no visible change

ariaLabel

aria-label="Assessment date" names the field when no label is shown

label

label="Assessment date"

required

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

helperText

helper-text="Pick the date the report covers"
Pick the date the report covers

error

error="Pick a date"
Pick a date

name

name="assessmentDate" posts the ISO date, no visible change

optional

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

optionalLabel

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

className

input-class="date-w-sm"
input-class="date-w-lg"
input-class="date-w-full"

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 date the report covers." adds an info tip

helpLabel

help-label="More information" (default)
help-label="About this date"

Guidance

What to do, and what to avoid.

Use it when

  • Capturing a single calendar date: assessment date, due date, date of birth.
  • You need one consistent calendar across every browser and both surfaces.
  • Restricting selection to a valid window with min / max.

Reach for something else when

  • You need a date and a time of day. → a date-time control
  • You are capturing a start-and-end range. → AppDateRangePicker
  • The value is free text, not a date. → AppInput
  • You are picking from a fixed list of labels. → AppSelect

Give the date a visible label

Do

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

Avoid

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

Set min and max bounds

Do

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

Avoid

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

Reference

Try every prop, read the full list, and check keyboard and screen reader behaviour.

0 1 2 3 4 5 6
dd-MMM-yyyy dd/MM/yyyy d MMMM yyyy yyyy-MM-dd
sm md lg
React, generated from the controls
<AppDatePicker label="Assessment date" name="pgDate" value={value} onChange={setValue} />
Razor, the same props
<app-date-picker label="Assessment date" name="pgDate" />

22 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 - ISO date string.
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 17 props

PropTypeDefaultDescription
namedefault - string - The form field name the ISO date posts under.
mindefault - string - The earliest selectable date, as an ISO date string.
maxdefault - string - The latest selectable date, as an ISO date string.
placeholderdefault Choose a date string Choose a date Text shown in the field while no date 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 md Control height tier, matching AppInput.
first-daydefault theme (1) 0 | 1 | 2 | 3 | 4 | 5 | 6 theme (1) First weekday of the calendar, 0 Sunday to 6 Saturday. Unset, it follows the theme's --wui-first-day token, which is 1 (Monday) unless the product sets it.
display-formatdefault dd-MMM-yyyy string dd-MMM-yyyy How the chosen date reads in the field, from the tokens yyyy, MMMM, MMM, MM, dd and d (for example dd/MM/yyyy). The posted value stays ISO.
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.
  • Required and disabled are set as native attributes on the control.

Do and avoid

2 pairs

Give the date a visible label

Do

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

Avoid

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

Set min and max bounds

Do

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

Avoid

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