Skip to content

Latest commit

 

History

History
158 lines (115 loc) · 11.4 KB

date-input.md

File metadata and controls

158 lines (115 loc) · 11.4 KB

Date input

GDS Date input component

Example

<govuk-date-input id="passport-issued" name-prefix="passport-issued" />

Date input

Example - with error message

<govuk-date-input id="passport-issued" name-prefix="passport-issued" error-message-prefix="Your passport issue date">
    <govuk-date-input-error-message>
        The date your passport was issued must be in the past
    </govuk-date-input-error-message>
</govuk-date-input>

Date input

Example - with fieldset

<govuk-date-input id="passport-issued" name-prefix="passport-issued" error-message-prefix="Your passport issue date">
    <govuk-date-input-fieldset>
        <govuk-date-input-fieldset-legend is-page-heading="true" class="govuk-fieldset__legend--l">
            When was your passport issued?
        </govuk-date-input-fieldset-legend>
        <govuk-date-input-hint>
            For example, 27 3 2007
        </govuk-date-input-hint>
        <govuk-date-input-error-message>
            The date your passport was issued must be in the past
        </govuk-date-input-error-message>
    </govuk-date-input-fieldset>
</govuk-date-input>

Date input

Example - with custom item labels

<govuk-date-input id="passport-issued" name-prefix="passport-issued">
    <govuk-date-input-day>
        <govuk-date-input-day-label>Dydd</govuk-date-input-day-label>
    </govuk-date-input-day>
    <govuk-date-input-month>
        <govuk-date-input-month-label>Mis</govuk-date-input-month-label>
    </govuk-date-input-month>
    <govuk-date-input-year>
        <govuk-date-input-year-label>Blwyddyn</govuk-date-input-year-label>
    </govuk-date-input-year>
</govuk-date-input>

Date input

Example - with custom item values

<govuk-date-input id="passport-issued" name-prefix="passport-issued" error-message-prefix="Your passport issue date">
    <govuk-date-input-day value="1" />
    <govuk-date-input-month value="4" />
    <govuk-date-input-year value="2022" />
</govuk-date-input>

Date input

API

<govuk-date-input>

The content is the HTML to use within the generated component.

Attribute Type Description
date-input-*` Additional attributes for the container element that wraps the items.
disabled bool? Whether the inputs should be disabled. The default is false.
error-message-prefix string The prefix to use in generated error messages.
for ModelExpression The model expression used to generate the name-prefix, id and value attributes as well as the error message content. The model type should be a Date, DateTime or a type that has a custom converter registered. See custom date types and documentation on forms for more information.
id string The id attribute for the main component. Required unless the for attribute is specified.
ignore-modelstate-errors bool Whether ModelState errors on the ModelExpression specified by the for attribute should be ignored when generating an error message. The default is false.
name-prefix string Optional prefix for the name attribute on each item's input.
readonly bool? Whether the inputs should be read-only. The default is false.
value object The date to populate the item values with. The value should be a Date, DateTime or a type that has a custom converter registered. See custom date types for more information.

<govuk-date-input-hint>

The content is the HTML to use within the component's hint.
Must be inside a <govuk-date-input> or <govuk-date-input-fieldset> element.

If the for attribute is specified on the parent <govuk-date-input> then content for the hint will be generated from the model expression.
If you want to retain the generated content and specify additional attributes then use a self-closing tag e.g. <govuk-date-input-hint class="some-additional-class" />.

<govuk-date-input-error-message>

The content is the HTML to use within the component's error message.
Must be inside a <govuk-date-input> or <govuk-date-input-fieldset> element.

If the for attribute is specified on the parent <govuk-date-input> then content for the error message will be generated from the model expression. (To prevent this set ignore-modelstate-errors on the parent <govuk-date-input> to false.) Specifying any content here will override any generated error message.
If you want to retain the generated content and specify additional attributes then use a self-closing tag e.g. <govuk-date-input-error-message visually-hidden-text="Error" />.

Attribute Type Description
error-items DateInputErrorComponents? The components of the date that have errors (day, month and/or year). By default this is resolved by looking up the errors that occurred on model binding. The fallback is DateInputErrorComponents.All.
visually-hidden-text string The visually hidden prefix used before the error message. The default is Error.

<govuk-date-input-fieldset>

A container element used when date input content should be contained with a fieldset element. When used every other child element must be placed inside this element, not the root <govuk-date-input>.
Must be inside a <govuk-date-input> element.

<govuk-date-input-fieldset-legend>

Required when a <govuk-date-input-fieldset> is specified
The content is the HTML to use within the legend.
Must be inside a <govuk-date-input-fieldset> element.

Attribute Type Description
is-page-heading boolean Whether the legend also acts as the heading for the page. The default is false.

<govuk-date-input-day>, <govuk-date-input-month>, <govuk-date-input-year>

Must be inside a <govuk-date-input> or <govuk-date-input-fieldset> element.

Attribute Type Description
autocomplete string The autocomplete attribute for the generated input element.
id string The id attribute for the item's geneated input element.
inputmode string The inputmode attribute for the item's generated input element. The default is numeric.
name string The name attribute for the item's generated input element.
pattern string The pattern attribute for the item's generated input element. The default is [0-9]*.
value string The value attribute for the item's generated input element.

<govuk-date-input-day-label>, <govuk-date-input-month-label>, <govuk-date-input-year-label>

Must be inside <govuk-date-input-day>, <govuk-date-input-month>, <govuk-date-input-year> respectively.

The content is the HTML to use within the item's label.

Custom date types

By default System.DateTime and GovUk.Frontend.AspNetCore.Date instances can be used as values for this component. A model binder converts the three inputs into a single instance of whatever model type is required. The model binder also tracks which components were invalid so that the correct items can be highlighted and a useful error message can be provided.

You can add support for additional types by implementing GovUk.Frontend.AspNetCore.DateInputModelConverter. See the sample at samples/DateInput/ for an example with NodaTime.