On this page
@addTagHelper *, Webority.Ui.RazorValue and onChange
The picker is controlled: value holds an ISO date string, and onChange gives back the new one.
ISO: 2026-07-10
Min and max
Constrain the selectable window with min and max so an invalid date cannot be picked.
Placeholder
Use a placeholder to say what the empty field expects, beside a label rather than in place of one.
Week start
Start the week on the day your people plan around, such as Sunday for a retail calendar.
Width
Size the field to the date it holds, since a date is short and does not need a full column.
Sizes
Match the field height to the inputs beside it, using sm in dense forms and lg on sign-in.
States
Disable a field that cannot change now, and mark a field that must be filled as required.
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 namemin / max: bounds
min="2026-07-01" (no max)max="2026-07-31" (no min)min and max togetherplaceholder
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 changeariaLabel
aria-label="Assessment date" names the field when no label is shownlabel
label="Assessment date"required
required="false" (default)required="true"helperText
helper-text="Pick the date the report covers"error
error="Pick a date"name
name="assessmentDate" posts the ISO date, no visible changeoptional
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 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 date the report covers." adds an info tiphelpLabel
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
A visible label above the field. The user knows what the date is for before opening it.
Only a placeholder as the label, which vanishes the moment a date is picked.
Set min and max bounds
min / max stop invalid dates at the source, so the user can only pick a real one.
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.
22 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 | - | 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
| Prop | Type | Default | Description |
|---|---|---|---|
| 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 pairsGive the date a visible label
A visible label above the field. The user knows what the date is for before opening it.
Only a placeholder as the label, which vanishes the moment a date is picked.
Set min and max bounds
min / max stop invalid dates at the source, so the user can only pick a real one.
No bounds, then reject the date after submit. Constrain up front instead.