Date Field Range

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

Anatomy

Date Field Range consists of four primary elements that enable users to select a start and end date in one masked field, with a calendar for visual selection.

Label - Identifies the field and its purpose
Start date - First segment of the masked field
End date - Second segment of the same field, after a hyphen
Helper text (Optional) - Description, format hint, warning, or error message

Options

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

Date Format Modes

Date Field Range 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

Behavior

Date Field Range 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 shows a message the product supplies. The field does not invent that message from the dates alone. Disabled state prevents interaction and closes an open calendar.

Manual entry

Both dates are typed into one field. The mask shows mm/dd/yyyy - mm/dd/yyyy (or dd/mm/yyyy - dd/mm/yyyy when that mode is selected), with a space, hyphen, and space between the ends. A single digit followed by / is padded, so 1/ becomes 01/. The field does not swap an end date that falls before the start date. That order stays as typed, and the range fails constraint validation.

Calendar interaction

Clicking the field opens the calendar and leaves focus in the input. Arrow Down opens the calendar and moves focus to the first control inside it. Users can move between months and select each end of the range. The calendar highlights the selected span and closes after the end date is selected, returning focus to the field. Choosing a day before the current start restarts the range at that day instead of storing an inverted pair. Dates outside the minimum and maximum, and dates marked unavailable, are disabled in the calendar.

Validation

Date Field Range checks the range as it changes and reports whether the text is complete and whether the range is allowed. It does not write an error message itself. The message under the field is the one the product provides. A range is complete when both ends are real dates. It is allowed when the last committed dates fall on available days, stay inside the minimum and maximum, and the start is not after the end. An empty range is allowed unless the field is required. An in-progress edit can still report the previous range as allowed, so wait until both dates are complete before showing a constraint error.

Usage Guidelines

Standard	Requirement
DoCapturing a date span	Capture a date span with both start and end dates
DoProviding calendar context	Provide calendar visual context for range selection
DoSupporting manual and visual entry	Support both manual entry and visual selection
DoValidating date ranges	Validate date ranges against constraints like minimum or maximum dates
DoLabel date ranges clearly	Write labels that clearly communicate the purpose of the range, include format hints, validate that start is before end, and show errors immediately; see Labeling and Range Validation.
Don’tSingle dates	Use Date Field Single instead
Don’tRecurring date ranges without year	Use Date Field Yearless Range for seasonal ranges or annual periods
Don’tTime selection	Use Time Field for time-only inputs
Don’tAmbiguous context or invalid ranges	Don’t omit format guidance or allow invalid date ranges without clear feedback; see Anti-pattern: Ambiguous Context and Invalid Ranges.

Alternatives

Date Field Range vs Date Field Yearless Range

Use Date Field Range when the year is essential to the date range selection, such as project timelines or reporting periods. Use Date Field Yearless Range when the year is irrelevant, such as recurring seasonal periods or annual date templates.

How to Use

Labeling and Range Validation

Provide clear, descriptive labels that communicate the purpose of the date range selection. Labels should indicate what the range represents and establish the relationship between start and end dates. Implement validation that ensures logical date ranges and provides immediate feedback when constraints are violated.

Write labels that clearly communicate the purpose of the date range selection
Keep the format hint visible when the date format might be unfamiliar
Set minimum and maximum dates to block dates outside the allowed span
Show an error when both dates are complete and the range still fails its constraints
Explain that the end date must be on or after the start date
Use the calendar when visual selection is helpful

Anti-pattern: Ambiguous Context and Invalid Ranges

Avoid creating confusion by omitting format guidance or allowing invalid date ranges without clear feedback.

Use Date Field Range for recurring annual periods where year doesn’t matter
Hide the format hint when the date format might be unfamiliar
Treat the first typed digit as a failed range
Leave a finished, inverted range without an error message
Use placeholder text to show the date format — the mask already fills the field, so a placeholder is never visible
Create labels that don’t clearly indicate what date range is being selected

Content

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

Labels should clearly indicate what date range is being selected
Error messages should explain why a date range 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 Range 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 and moves focus into it
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 (for range selection)
Space	Selects the focused date (for range selection)
Esc	Closes the calendar picker

Accessibility

Date Field Range 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
DateFieldRange Props
DateFieldRangeChange
DateFieldRangeValue

Common Examples

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

function ExampleComponent() {
  return (
    <DateFieldRange
      label="Reporting period"
      defaultValue={{
        startDate: "1999-12-25",
        endDate: "2000-01-01",
      }}
    />
  );
}

Date string values

DateFieldRange accepts and returns date-only ISO 8601 strings (YYYY-MM-DD) for startDate and endDate. onChange returns that same date-only form, or null when an end is empty. A full ISO datetime is accepted and normalized to the calendar date in that string’s offset; the day in the string is kept. When you start from a JavaScript Date, build the string from the local year, month, and day. toISOString() is UTC, so it can name a different calendar date than the local one you mean to store.The field is one masked input, not two. The displayed value looks like mm/dd/yyyy - mm/dd/yyyy, with a space, hyphen, and space between the ends. A single digit followed by / is zero-padded (1/ becomes 01/). Typing does not swap an end date that is earlier than the start.

Default values

Pass defaultValue for an uncontrolled field. The field keeps later edits itself. Use null to start empty.

Controlled usage

Store a DateFieldRangeValue in state and pass it as value. onChange receives a DateFieldRangeChange, which adds validity flags the value prop does not accept. Copy startDate and endDate back into state. Pass null to clear both ends.

Constraint errors

The field reports validity and leaves the message to you. isInputValid is true only when both ends are complete dates. isDateRangeValid is a separate check on the last committed dates: an empty range passes unless required is set. An in-progress edit can leave isDateRangeValid true while isInputValid is false, because an incomplete end keeps the previous committed date. Show error only after isInputValid is true and the range is still not allowed. error also sets aria-invalid. A boolean true is the error style with no message.

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

timezone sets the calendar’s Today action and, when the field has no value, the month it opens on. When the zone differs from the browser time zone, the calendar shows “Dates shown in” plus that zone’s abbreviation.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.

React Accessibility

The input is a textbox. With a string label, the visible label is associated with the input. hideLabel moves that string to aria-label and strips inline markdown. With no label, the input’s accessible name is “Select a date range”.required marks the input required and adds a visible asterisk plus screen-reader text on the label. error sets aria-invalid. Error text is announced with aria-live="assertive". Warning text uses aria-live="polite".Arrow Down opens the calendar and moves focus to the first control in the popover. Escape closes the calendar and returns focus to the input. Inside the calendar, arrow keys move by day or week, Page Up and Page Down move by month, and Shift plus those keys moves by year. Enter or Space selects the focused day. Selecting the end date closes the calendar and returns focus to the input.

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:

<DateFieldRange data-cy="booking-range" label="Booking range" />

cy.get('[data-cy="booking-range"]').type("06/15/2025 - 06/20/2025");

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

The masked input also exposes the current range for assertions:

Attribute	Meaning
`data-start-date`	Committed start as `YYYY-MM-DD`, or empty
`data-end-date`	Committed end as `YYYY-MM-DD`, or empty
`data-input-valid`	`"true"` when both ends are complete dates
`data-input-empty`	`"true"` when no date digits remain
`data-date-range-valid`	`"true"` when the range passes constraints, including a non-required empty range

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 { DateFieldRange } from "@servicetitan/anvil2";

function ExampleComponent() {
  return (
    <DateFieldRange
      label="Reporting period"
      defaultValue={{
        startDate: "1999-12-25",
        endDate: "2000-01-01",
      }}
      mode="mm/dd/yyyy"
      disableHint={false}
      disableCalendar={false}
      required={false}
    />
  );
}

`DateFieldRange` Props

Every prop below is optional. id, name, and data-* attributes are forwarded to the masked input. className, style, and layout props land on the text field element.The field does not accept prefix (the calendar icon is built in), hint (the format line replaces it), showCounter, autoComplete (always "off"), onClick, or onKeyDown.

{ startDate: string | null; endDate: string | null } | null

Initial range for uncontrolled use. Pass null to start empty. Date-only ISO strings (YYYY-MM-DD).

boolean

default:"false"

Renders the masked input without the popover calendar. Arrow Down and click no longer open a calendar.

boolean

default:"false"

Hides the format hint under the field (Format: mm/dd/yyyy or Format: dd/mm/yyyy).

string

Latest date either end may use. Date-only ISO string. Later dates are disabled in the calendar and fail isDateRangeValid.

string

Earliest date either end may use. Date-only ISO string. Earlier dates are disabled in the calendar and fail isDateRangeValid.

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

default:"mm/dd/yyyy"

Order of month, day, and year in the mask and the format hint.

(event: React.FocusEvent) => void

Called when the input loses focus, including when focus moves into the calendar. Not called when disableCalendar is set. Leaving the field entirely also closes an open calendar.

(change: DateFieldRangeChange) => void

Called when the parsed range or either validity flag changes. Copy startDate and endDate into value. The full change object is not a DateFieldRangeValue.

(event: React.FocusEvent) => void

Called when the input receives focus. Not called when disableCalendar is set.

boolean

default:"false"

Marks the input required. An empty range then fails isDateRangeValid. Does not render an error message by itself.

IanaZone

IANA time zone for the calendar’s Today action and, when the field has no value, the month it opens on. A different zone than the browser’s shows “Dates shown in” plus the zone abbreviation. Example: "America/Los_Angeles".

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

Dates and weekdays that cannot be selected. dates are date-only ISO strings. daysOfWeek uses Luxon numbers: Monday is 1 and Sunday is 7. Matching days are disabled in the calendar and fail isDateRangeValid.

{ startDate: string | null; endDate: string | null } | null

Controlled range. Pass null to clear both ends. Date-only ISO strings (YYYY-MM-DD).

Additional field props

ReactElement | string

Secondary copy under the format hint.

boolean

default:"false"

Prevents interaction and closes an open calendar.

boolean | string | string[] | ReactElement

Applies the error style and sets aria-invalid. A string or string array is also shown under the field. true is the style with no message.

Passing a ReactElement is deprecated. Use a string or string[].

"off" | "polite" | "assertive"

Deprecated and ignored. Error text always uses aria-live="assertive".

boolean

default:"false"

Hides the visible label and uses the label string as the input’s aria-label. Inline markdown is stripped. Requires label.

boolean

default:"false"

Applies a subdued primary background to draw attention to the field.

ReactNode

Accessible name for the field. A string supports inline markdown: bold (**text**), italic (*text*), bold and italic (***text***), highlight (==text==), and code (`text`).

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.

FieldLabelProps

Props for the FieldLabel, including aiMark. The visible label text still comes from label.

boolean

default:"false"

Shows a spinner after the input.

number

Maximum characters the input accepts. The mask is 23 characters (mm/dd/yyyy - mm/dd/yyyy), so a smaller limit blocks a complete range. This field has no character counter.

ReactNode

Tooltip content for the info button after the label.

string

Has no visible effect. The mask keeps a value in the field, so the HTML placeholder never appears. Use the format hint or description to explain the expected format.

"small" | "medium" | "large"

default:"medium"

Field height: small is 32px, medium is 40px, and large is 48px.

string | ReactElement

Content after the input. Hidden from assistive technology.

default:"text"

Forwarded to the masked input. Leave it as "text" so typed dates reach the mask. Other values block normal date entry.

string | string[]

Warning copy under the field, announced with aria-live="polite".

DateFieldRangeChange

onChange receives this object. It is not the controlled value.

string | null

Last committed end as a date-only ISO string, such as "2025-07-02", or null when that end is empty or incomplete.

boolean

Whether the last committed dates satisfy required, unavailable dates, unavailable weekdays, and minDate / maxDate, and the start is not after the end. Independent of isInputValid. An empty range is valid unless required is set. An incomplete edit can leave this true while the text is still unfinished.

boolean

Whether no date digits remain after the mask placeholder is removed. The field can look filled with mm/dd/yyyy - mm/dd/yyyy and still be empty.

boolean

Whether both ends are complete dates. Independent of constraints: an inverted or unavailable range can still be true.

string | null

Last committed start as a date-only ISO string, such as "2025-03-22", or null when the start is empty or incomplete.

DateFieldRangeValue

The controlled value and uncontrolled defaultValue use this type. Pass null to clear both ends. An object value has these fields. This is not the object onChange receives.

string | null

End as a date-only ISO string (YYYY-MM-DD), or null when that end is empty.

string | null

Start as a date-only ISO string (YYYY-MM-DD), or null when the start is empty.

​Anatomy

​Options

​Date Format Modes

​Sizes

​Behavior

​Visual States

​Manual entry

​Calendar interaction

​Validation

​Usage Guidelines

​Alternatives

​Date Field Range vs Date Field Yearless Range

​How to Use

​Labeling and Range Validation

​Anti-pattern: Ambiguous Context and Invalid Ranges

​Content

​Keyboard Interaction

​Input Field

​Calendar Picker

​Accessibility

​Code

​Common Examples

​Date string values

​Default values

​Controlled usage

​Constraint errors

​Disabled hint text

​Timezone

​Disable calendar popover

​Markdown in labels

​Hide the label

​React Accessibility

​Testing

​DateFieldRange Props

​Additional field props

​DateFieldRangeChange

​DateFieldRangeValue

Anatomy

Options

Date Format Modes

Sizes

Behavior

Visual States

Manual entry

Calendar interaction

Validation

Usage Guidelines

Alternatives

Date Field Range vs Date Field Yearless Range

How to Use

Labeling and Range Validation

Anti-pattern: Ambiguous Context and Invalid Ranges

Content

Keyboard Interaction

Input Field

Calendar Picker

Accessibility

Code

Common Examples

Date string values

Default values

Controlled usage

Constraint errors

Disabled hint text

Timezone

Disable calendar popover

Markdown in labels

Hide the label

React Accessibility

Testing

`DateFieldRange` Props

Additional field props

DateFieldRangeChange

DateFieldRangeValue