Date Field Single

For development, import DateFieldSingle from @servicetitan/anvil2. For design, find it in the Anvil2 file.

Anatomy

Date Field Single consists of five primary elements that enable users to select a single date through text input or a calendar picker.

Label - Identifies the field and its purpose
Input field - Text input for manual date entry with format mask
Helper text (Optional) - Description, format hint or error message

Options

Date Field Single supports the following configurations to accommodate different use cases and regional preferences.

Date Format Modes

Date Field Single supports two date format modes to match regional conventions. The default format is mm/dd/yyyy for US audiences, while dd/mm/yyyy is available for international users.

Mode	Format	Use Case
mm/dd/yyyy	Default	US date format
dd/mm/yyyy	Optional	International date format

Sizes

Three size options accommodate different layout densities and visual hierarchies.

Size	Height
Small	32px
Medium	40px
Large	48px

Calendar Picker

The calendar picker can be disabled when manual text entry is preferred or when the calendar interface is not suitable for the use case.

Behavior

Date Field Single responds to user interaction with distinct visual states and validation feedback.

Visual States

The component displays different visual states to communicate field status and interactivity. Default state shows the field ready for input. Focus state highlights the active field. Error state displays validation messages when dates are invalid or required fields are empty. Disabled state prevents interaction while maintaining visual context.

Calendar Interaction

Clicking the input field opens a popover calendar. Users can navigate months and select dates directly from the calendar. The calendar closes automatically after selection, and the selected date populates the input field.

Validation

Date Field Single validates input in real time. The component checks for parseable dates, required field completion, date constraints (min/max dates), and unavailable dates or days of the week. Error messages appear below the field when validation fails.

Usage Guidelines

Standard	Requirement
DoCapturing a single date	Capture a single, specific date
DoProviding calendar context	Provide calendar visual context for date selection
DoSupporting manual and visual entry	Support both manual entry and visual selection
DoValidating dates	Validate dates against constraints like minimum or maximum dates
DoLabel dates clearly	Write labels that clearly communicate the purpose of the date selection, include format hints, set date constraints, and show validation errors immediately; see Labeling and Context.
Don’tDate ranges	Use Date Field Range instead
Don’tRecurring dates without year	Use Date Field Yearless for birthdays, anniversaries, or seasonal dates
Don’tTime selection	Use Time Field for time-only inputs
Don’tAmbiguous context or format	Don’t omit format guidance or use Date Field Single for dates where year information is irrelevant; see Anti-pattern: Ambiguous Context and Format.

Alternatives

Date Field Single vs Date Field Yearless

Use Date Field Single when the year is essential to the date selection, such as appointment scheduling or deadline setting. Use Date Field Yearless when the year is irrelevant, such as recurring annual events or template dates.

How to Use

Labeling and Context

Provide clear, descriptive labels that communicate the purpose of the date selection. Labels should indicate what the date represents and why it’s needed. Use helper text or descriptions when additional context helps users understand constraints or requirements.

Write labels that clearly communicate the purpose of the date selection
Include format hints to guide users on expected input format
Set appropriate date constraints (min/max dates) to prevent invalid selections
Display validation errors immediately when they occur
Use the calendar picker to provide visual date selection when helpful

Anti-pattern: Ambiguous Context and Format

Avoid creating confusion by omitting format guidance or using Date Field Single for dates where year information is irrelevant.

Use Date Field Single for recurring annual events where year doesn’t matter
Omit format hints when the date format might be ambiguous to users
Hide validation errors until form submission
Use placeholder text to communicate date format instead of format hints
Create labels that don’t clearly indicate what date is being selected

Content

Content within Date Field Single should be clear, concise, and actionable.

Labels should clearly indicate what date is being selected
Error messages should explain why a date is invalid and how to fix it
Format hints should match the selected mode (mm/dd/yyyy or dd/mm/yyyy)
Descriptions should provide context without overwhelming the user

Keyboard Interaction

Users can navigate Date Field Single using standard keyboard controls.

Input Field

Key	Description
Tab	Moves focus to the next element
Shift + Tab	Moves focus to the previous element
Arrow Down	Opens the calendar picker when focused
Esc	Closes the calendar picker

Calendar Picker

Key	Description
Arrow Left	Moves focus to the previous day
Arrow Right	Moves focus to the next day
Arrow Up	Moves focus to the same day in the previous week
Arrow Down	Moves focus to the same day in the next week
Page Up	Moves focus to the same day in the previous month
Page Down	Moves focus to the same day in the next month
Shift + Page Up	Moves focus to the same day in the previous year
Shift + Page Down	Moves focus to the same day in the next year
Enter	Selects the focused date
Space	Selects the focused date
Esc	Closes the calendar picker

Accessibility

Date Field Single includes built-in accessibility features. The component supports full keyboard navigation and screen reader compatibility. Ensure labels are descriptive and error messages are clear for assistive technology users. For more guidance on form field labels and context, see input field context association best practices.

Code

Implementation
DateFieldSingle Props
DateFieldSingleChange

Common Examples

import { DateFieldSingle } from "@servicetitan/anvil2";

function ExampleComponent() {
  return <DateFieldSingle defaultValue={new Date().toISOString()} />;
}

Date string values

DateFieldSingle accepts and returns ISO 8601 date strings (for example, "2025-07-02") rather than JavaScript Date objects. Convert Date values from API clients or Anvil1 Date Picker before passing them to the component.

Default values

Default values can be included in DateFieldSingle to use the field in an uncontrolled mode.

Controlled usage

The DateFieldSingle can be controlled. This means you can maintain the state outside the component. Listen for new dates with onChange and supply a date into the value prop.

Validation

Understanding the object passed back in onChange is key to understanding how to validate this field.isDateValid will tell you if the last entered date is valid according to the props you’ve supplied (e.g. required, minDate, maxDate, and unavailable).isInputValid will tell you only if the underlying input is a parseable date — this does not consider whether the date is good according the other props.isInputEmpty will tell you if the underlying input has no digits entered.Typically, you will want to use these values together to determine the overall validity of the field. Though the simplest implementation may likely suffice to use only isDateValid.

Disabled hint text

The hint text can be disabled. If the hint text is disabled, ensure that the date format is displayed on the page.

Timezone

The timezone prop controls the meaning of the “Today” button and which month-year the calendar initially displays. When the timezone differs from the user’s locale, a disambiguation message appears below the calendar.The display of the Calendar can be prevented by passing disableCalendar.

Markdown in labels

The label prop supports inline markdown: bold (**text**), italic (*text*), bold and italic (***text***), highlight (==text==), and code (`text`).

Hide the label

Use hideLabel to visually hide the label. The label string is converted to an aria-label on the input so it remains accessible to screen readers — any inline markdown is stripped to plain text.

Testing

The field’s interactive sub-elements carry a stable data-anv-part attribute so end-to-end tests can target them directly. The library owns the part names; you supply the instance identifier.Attach your own data-* attribute (such as data-cy or data-testid) to the field. It is forwarded to the masked text input — the one element present in every mode, including disableCalendar:

<DateFieldSingle data-cy="start-date" label="Start date" />

cy.get('[data-cy="start-date"]').type("06/15/2025");

`data-anv-part`	Element
`date-input`	Masked text input
`popover`	Calendar popover container
`date-calendar`	Calendar surface inside the popover

The popover and calendar render in the browser’s top layer, outside the input’s subtree, so a descendant query scoped to your data-cy on the input will not reach them. Target them by their part attribute directly ([data-anv-part="date-calendar"]) or by the popover’s data-testid="calendar-popover". Only one calendar is open at a time.

import { DateFieldSingle } from "@servicetitan/anvil2";

function ExampleComponent() {
return (

<DateFieldSingle
  defaultValue={new Date().toISOString()}
  mode="mm/dd/yyyy"
  disableHint={false}
  disableCalendar={false}
  required={false}
/>
); }

`DateFieldSingle` Props

string | null

Uncontrolled initial value for the date range.

(change: DateFieldSingleChange) => void

Callback fired when the value changes.

string | null

Controlled value for the date range (ISO 8601 strings).

boolean

default:"false"

If true, disables the calendar popover.

boolean

default:"false"

If true, disables the format hint below the field.

string

Maximum selectable date (ISO 8601).

string

Minimum selectable date (ISO 8601).

"mm/dd/yyyy" | "dd/mm/yyyy"

default:"mm/dd/yyyy"

Date input format.

boolean

default:"false"

If true, the field is required.

IanaZone

IANA timezone identifier (e.g., “America/Los_Angeles”). Controls the “Today” button behavior and initial calendar display. Shows a disambiguation message when different from the user’s locale timezone.

{ dates?: string[]; daysOfWeek?: (1 | 2 | 3 | 4 | 5 | 6 | 7)[] }

Dates or days of week that are unavailable for selection.

Additional field props

string

Additional description below the field.

boolean

default:"false"

If true, disables the field.

ReactElement | string | boolean

Error message or state.

"off" | "polite" | "assertive"

default:"assertive"

ARIA live region setting for error messages.

boolean

default:"false"

Visually hides the label while keeping it accessible to screen readers via aria-label.

ReactNode

Label for the field. Supports inline markdown formatting.

Omitting label is deprecated and will be required in v4.0.0. Use hideLabel to visually hide it. Passing ReactNode is also deprecated — use a plain string with inline markdown instead.

Omit<FieldLabelProps, "children" | "id" | "htmlFor">

Additional props passed to the FieldLabel component. Supports the aiMark prop for displaying AI-powered field indicators.

boolean

default:"false"

If true, shows a loading spinner.

ReactNode

Additional info icon or content for the label.

string

Placeholder text.

"small" | "medium" | "large"

default:"medium"

Input size.

string | ReactElement

Suffix element to display inside the input.

default:"text"

Input type.

DateFieldSingleChange

The onChange callback receives a DateFieldSingleChange object with the following properties:

string | null

The date in ISO 8601 format (e.g., “2025-07-02”).

boolean

Whether the date is valid according to all constraints (required, unavailable dates/days, min/max date, etc.).

boolean

Whether the input is empty.

boolean

Whether the input matches the format and is not empty.

Concepts & Guidelines

Anvil2

Resources

Date Field Single - Web

Anatomy

Options

Date Format Modes

Sizes

Calendar Picker

Behavior

Visual States

Calendar Interaction

Validation

Usage Guidelines

Alternatives

Date Field Single vs Date Field Yearless

How to Use

Labeling and Context

Anti-pattern: Ambiguous Context and Format

Content

Keyboard Interaction

Input Field

Calendar Picker

Accessibility

Code

Common Examples

Date string values

Default values

Controlled usage

Validation

Disabled hint text

Timezone

Disable calendar popover

Markdown in labels

Hide the label

Testing

`DateFieldSingle` Props

Additional field props

DateFieldSingleChange

​Anatomy

​Options

​Date Format Modes

​Sizes

​Calendar Picker

​Behavior

​Visual States

​Calendar Interaction

​Validation

​Usage Guidelines

​Alternatives

​Date Field Single vs Date Field Yearless

​How to Use

​Labeling and Context

​Anti-pattern: Ambiguous Context and Format

​Content

​Keyboard Interaction

​Input Field

​Calendar Picker

​Accessibility

​Code

​Common Examples

​Date string values

​Default values

​Controlled usage

​Validation

​Disabled hint text

​Timezone

​Disable calendar popover

​Markdown in labels

​Hide the label

​Testing

​DateFieldSingle Props

​Additional field props

​DateFieldSingleChange

Anatomy

Options

Date Format Modes

Sizes

Calendar Picker

Behavior

Visual States

Calendar Interaction

Validation

Usage Guidelines

Alternatives

Date Field Single vs Date Field Yearless

How to Use

Labeling and Context

Anti-pattern: Ambiguous Context and Format

Content

Keyboard Interaction

Input Field

Calendar Picker

Accessibility

Code

Common Examples

Date string values

Default values

Controlled usage

Validation

Disabled hint text

Timezone

Disable calendar popover

Markdown in labels

Hide the label

Testing

`DateFieldSingle` Props

Additional field props

DateFieldSingleChange