Date Field Yearless Range

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

Anatomy

Date Field Yearless Range consists of seven primary elements that enable users to select a start and end date without year information.

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

Options

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

Date Format Modes

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

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

Sizes

Three size options accommodate different layout densities and visual hierarchies.

Size	Height
Small	32px
Medium	40px
Large	48px

Date Picker

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

Behavior

Date Field Yearless 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 both fields ready for input. Focus state highlights the active field. Error state displays validation messages when date ranges are invalid, start dates are after end dates, or required fields are empty. Disabled state prevents interaction while maintaining visual context.

Date Picker Interaction

Clicking either input field opens a popover with two scrollable lists for month and day selection. Users can scroll through months and days and select values directly from the lists. The picker closes automatically after selection, and the selected month and day populate the respective input field.

Validation

Date Field Yearless Range validates input in real time. The component checks for parseable month and day values, required field completion, date constraints (min/max dates), unavailable dates, and logical range validation (start date must be before or equal to end date). Error messages appear below the fields when validation fails.

Usage Guidelines

Standard	Requirement
DoCapturing recurring date ranges	Capture recurring date ranges where year is irrelevant
DoSelecting seasonal periods	Select seasonal periods or annual date ranges
DoInputting recurring annual events	Input date ranges for recurring annual events
DoCreating date range templates	Create date range templates for annual use
DoLabel yearless ranges clearly	Write labels that clearly indicate year isn’t needed, include format hints, validate the range, and maintain consistency alongside year-specific ranges; see Labeling and Yearless Range Validation.
Don’tSpecific date ranges with year	Use Date Field Range instead
Don’tSingle dates	Use Date Field Single or Date Field Yearless instead
Don’tTime selection	Use Time Field for time-only inputs
Don’tAmbiguous context or invalid ranges	Don’t use Date Field Yearless Range for ranges that require year information or allow invalid ranges without clear feedback; see Anti-pattern: Ambiguous Context and Invalid Ranges.

Alternatives

Date Field Yearless Range vs Date Field Range

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

How to Use

Labeling and Yearless Range Validation

Provide clear, descriptive labels that communicate the purpose of the date range selection and indicate that year information is not required. Labels should clarify that only month and day ranges are needed, helping users understand why year input is omitted. Implement validation that ensures logical date ranges and provides immediate feedback when constraints are violated.

Write labels that clearly communicate the purpose and indicate year is not needed
Include format hints to guide users on expected input format (mm/dd or dd/mm)
Set appropriate date constraints (min/max dates) when applicable to prevent invalid selections
Validate that start date is before or equal to end date
Display validation errors immediately when they occur
Use Date Field Yearless Range for recurring date ranges where year context is not needed
Maintain consistency when using yearless ranges alongside year-specific ranges in forms

Anti-pattern: Ambiguous Context and Invalid Ranges

Avoid creating confusion by using Date Field Yearless Range for ranges that require year information or allowing invalid date ranges without clear feedback.

Use Date Field Yearless Range for date ranges that require year information
Omit format hints when the date format might be ambiguous to users
Hide validation errors until form submission
Allow start dates to be after end dates without clear error messaging
Use placeholder text to communicate date format instead of format hints
Mix yearless date ranges with year-specific date ranges in the same form without clear visual or contextual distinction
Create labels that don’t indicate year is not required

Content

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

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

Keyboard Interaction

Users can navigate Date Field Yearless Range using standard keyboard controls.

Input Fields

Key	Description
Tab	Moves focus between start and end date inputs
Shift + Tab	Moves focus to the previous element
Arrow Down	Opens the date picker when focused
Esc	Closes the date picker

Date Picker

Key	Description
Arrow Up	Moves focus to the previous item in the list
Arrow Down	Moves focus to the next item in the list
Esc	Closes the date picker

Accessibility

Date Field Yearless Range includes built-in accessibility features. The component uses semantic grouping to associate the start and end date inputs. 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
DateFieldYearlessRange Props

Common Examples

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

function ExampleComponent() {
  return <DateFieldYearlessRange label="Date Range" />;
}

Controlled vs Uncontrolled

The DateFieldYearlessRange component can be used in controlled or uncontrolled mode.

Uncontrolled

Use defaultValue to set an initial value without controlling the state.

Controlled

Use value and onChange for full control over the component state.

Date Format Modes

The component supports two date format modes: mm/dd (default) and dd/mm.

With Validation

Show error states when validation fails.

Sizes

The component supports small, medium, and large sizes.

Custom Labels

Customize the accessible labels for the start and end date fields.

React Accessibility

The component uses a fieldset with a legend for proper grouping
Start and end date fields have individual accessible labels (visually hidden)
Error messages are announced via aria-live
The moreInfo tooltip content is also available to screen readers

For more guidance on form field labels and context, see input field context association best practices.

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 kept as a screen-reader-only <legend> element so the group remains accessible — any inline markdown is stripped to plain text.

Testing

Interactive sub-elements carry a stable data-anv-part attribute so end-to-end tests can target them. Attach your own data-* (such as data-cy) to the field — it is forwarded to the fieldset root:

<DateFieldYearlessRange data-cy="service-period" label="Service period" />

cy.get('[data-cy="service-period"] [data-anv-part="start-input"]').type("01/01");
cy.get('[data-cy="service-period"] [data-anv-part="end-input"]').type("12/31");

`data-anv-part`	Element
`start-input`	Start masked month/day input
`end-input`	End masked month/day input

The shared yearless picker also stamps popover, month-list, day-list, and option (see Date Field Yearless Testing). Those parts render in the top layer and are not descendants of the fieldset.

<DateFieldYearlessRange
  label="Date Range"
  mode="mm/dd"
  value={{ startDate: { month: 6, day: 1 }, endDate: { month: 8, day: 31 } }}
  onChange={(change) => console.log(change)}
  required={false}
  error={false}
  size="medium"
/>

`DateFieldYearlessRange` Props

The DateFieldYearlessRange component accepts the following props as well as layout utility props.

string

required

Label for the field. Supports inline markdown formatting.

DateFieldYearlessRangeValue

Default value for uncontrolled usage. Object with startDate and endDate properties, each containing month and day numbers.

ReactElement | string

Helper text displayed below the input.

boolean

Whether the field is disabled.

boolean

Whether to hide the format hint (e.g., “Format: mm/dd”).

boolean

Whether to disable the date picker popup.

string

default:"End date"

Accessible label for the end date input (visually hidden).

ReactElement | string | boolean

Error message or error state for the field.

"off" | "polite" | "assertive"

default:"assertive"

The aria-live value for error messages.

boolean

default:"false"

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

string

Custom ID for the field.

Omit<FieldLabelProps, "el">

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

"mm/dd" | "dd/mm"

default:"mm/dd"

The date format mode.

ReactNode

Additional information to display in a tooltip next to the label.

(event: React.FocusEvent) => void

Callback when the field loses focus.

(change: DateFieldYearlessRangeChange) => void

Callback when the date range value changes.

(event: React.FocusEvent) => void

Callback when the field receives focus.

boolean

Whether the field is required.

"small" | "medium" | "large"

The size of the input fields.

string

default:"Start date"

Accessible label for the start date input (visually hidden).

DateFieldYearlessRangeValue

Controlled value. Object with startDate and endDate properties, each containing month and day numbers or null.

Types

type YearlessDate = {
  month: number; // 1-12
  day: number;   // 1-31
};

type DateFieldYearlessRangeValue = {
  startDate: YearlessDate | null;
  endDate: YearlessDate | null;
};

type DateFieldYearlessRangeChange = {
  startDate: YearlessDate | null;
  endDate: YearlessDate | null;
};

Concepts & Guidelines

Anvil2

Resources

Date Field Yearless Range - Web

Anatomy

Options

Date Format Modes

Sizes

Date Picker

Behavior

Visual States

Date Picker Interaction

Validation

Usage Guidelines

Alternatives

Date Field Yearless Range vs Date Field Range

How to Use

Labeling and Yearless Range Validation

Anti-pattern: Ambiguous Context and Invalid Ranges

Content

Keyboard Interaction

Input Fields

Date Picker

Accessibility

Code

Common Examples

Controlled vs Uncontrolled

Uncontrolled

Controlled

Date Format Modes

With Validation

Sizes

Custom Labels

React Accessibility

Markdown in labels

Hide the label

Testing

`DateFieldYearlessRange` Props

Types

​Anatomy

​Options

​Date Format Modes

​Sizes

​Date Picker

​Behavior

​Visual States

​Date Picker Interaction

​Validation

​Usage Guidelines

​Alternatives

​Date Field Yearless Range vs Date Field Range

​How to Use

​Labeling and Yearless Range Validation

​Anti-pattern: Ambiguous Context and Invalid Ranges

​Content

​Keyboard Interaction

​Input Fields

​Date Picker

​Accessibility

​Code

​Common Examples

​Controlled vs Uncontrolled

​Uncontrolled

​Controlled

​Date Format Modes

​With Validation

​Sizes

​Custom Labels

​React Accessibility

​Markdown in labels

​Hide the label

​Testing

​DateFieldYearlessRange Props

​Types

Anatomy

Options

Date Format Modes

Sizes

Date Picker

Behavior

Visual States

Date Picker Interaction

Validation

Usage Guidelines

Alternatives

Date Field Yearless Range vs Date Field Range

How to Use

Labeling and Yearless Range Validation

Anti-pattern: Ambiguous Context and Invalid Ranges

Content

Keyboard Interaction

Input Fields

Date Picker

Accessibility

Code

Common Examples

Controlled vs Uncontrolled

Uncontrolled

Controlled

Date Format Modes

With Validation

Sizes

Custom Labels

React Accessibility

Markdown in labels

Hide the label

Testing

`DateFieldYearlessRange` Props

Types