Date Field Range

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.

Anvil2 Web

Resources

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

​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

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