Calendar - Web

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

Anatomy

The Calendar consists of nine primary elements that work together to enable date viewing and selection.

Header - Navigation toolbar containing month and year controls
Month button - Opens month selection view
Year button - Opens year selection view
Previous button - Navigates to the previous month
Next button - Navigates to the next month
Today button - Navigates to today’s date
Month grid - Table displaying days in a month
Day cell - A single cell in the month grid
Selected day - Selected date

Options

The Calendar supports the following configurations to accommodate various date selection scenarios.

Selection Mode

Calendar supports single date selection and date range selection modes. Single date mode allows selecting one date, while range mode enables selecting a start and end date.

Start Day

Start day	Description
Sunday	Calendar week begins on Sunday (default)
Monday	Calendar week begins on Monday

Date Restrictions

Calendar supports date restrictions through minimum and maximum date boundaries. Dates outside the specified range are disabled and cannot be selected.

Unavailable Dates

Mark specific dates or days of the week as unavailable when they cannot be selected. Unavailable dates are visually distinct and cannot be selected.

Locale and Timezone

Calendar adapts to different locales for date formatting and week start days. Timezone configuration ensures dates are interpreted correctly across different regions.

Behavior

The Calendar responds to user interaction with distinct visual states and navigation patterns.

Selection States

Selected dates display with distinct visual styling. In range mode, the start date, end date, and dates within the range are visually indicated. Hover states provide feedback during date selection. Users navigate between months using Previous and Next buttons. Month and Year buttons switch to selection views for faster navigation across longer time periods. The Today button quickly returns focus to the current date.

View Transitions

Calendar transitions between day, month, and year selection views. The header controls adapt based on the current view, showing relevant navigation options for each context.

Date Constraints

When date restrictions or unavailable dates are configured, disabled dates are visually distinct and cannot receive focus or selection. Navigation automatically skips unavailable dates when using keyboard controls.

Usage Guidelines

Standard	Requirement
DoSelecting a single date	Allow users to select a single date for scheduling, filtering, or data entry
DoSelecting a date range	Enable date range selection for filtering data or scheduling periods
DoDisplaying a calendar grid	Display dates in a familiar calendar grid format
DoSelecting dates within forms	Provide date selection within forms or date input fields
DoSet date boundaries	Set minimum and maximum date boundaries when business rules or data availability create constraints; see Set date boundaries to guide user choices.
DoMark unavailable dates	Mark specific dates or recurring days as unavailable when they cannot be selected; see Mark unavailable dates to communicate constraints.
Don’tSimple date input	Use DateField for text-based date entry when users prefer typing dates
Don’tTime selection	Calendar focuses on dates only; use TimeField for time selection
Don’tDisplay-only dates	Use text or other display components when dates are not selectable

Alternatives

Calendar vs DateField

DateField provides text-based date input with calendar popover support. Use DateField when space is limited or users prefer typing dates. Use Calendar when you need a persistent calendar view or when date selection is the primary interaction.

How to Use

Choose single or range selection based on user needs

Use single date selection when users need to pick one specific date, such as a deadline, appointment date, or event date. Single selection provides clear focus and reduces cognitive load for straightforward date choices. Use date range selection when users need to define a period, such as vacation dates, report date ranges, or filtering time periods. Range selection helps users visualize the span and understand the relationship between start and end dates. Use single date selection for specific point-in-time selections. This pattern works well for scheduling, deadlines, and one-time events where users need clarity about a single date. Use date range selection when users need to define periods or spans. This pattern helps users understand duration and relationships between dates, making it ideal for filtering, reporting, and multi-day activities.

Set date boundaries to guide user choices

Use minimum and maximum date boundaries to prevent invalid selections and guide users toward appropriate date choices. Boundaries help users understand constraints before they attempt invalid selections, reducing errors and frustration. Set date boundaries when business rules or data availability create constraints. Clear boundaries help users understand what dates are valid, preventing errors and reducing support requests.

Mark unavailable dates to communicate constraints

Mark specific dates or recurring days as unavailable when they cannot be selected due to business rules, holidays, or system constraints. Visual distinction helps users understand why certain dates aren’t selectable and prevents confusion. Mark unavailable dates clearly to communicate constraints to users. This helps users understand why certain dates aren’t selectable and prevents frustration from attempting invalid selections.

Content

Content within the Calendar should be clear and accessible, helping users understand date availability and navigate efficiently.

Use appropriate locale settings to format dates according to user expectations
Ensure date restrictions are clearly communicated through visual styling
Provide clear visual feedback for selected dates and date ranges
Maintain consistent date formatting throughout the calendar interface

Keyboard Interaction

Users can navigate the Calendar using standard keyboard controls.

Key	Description
Tab	Move focus between header controls
Arrow Left	Move focus to the previous day
Arrow Right	Move focus to the next day
Arrow Up	Move focus to the same day in the previous week
Arrow Down	Move focus to the same day in the next week
Home	Move focus to the first day of the current week
End	Move focus to the last day of the current week
Page Up	Move focus to the same day in the previous month
Page Down	Move focus to the same day in the next month
Enter	Select the focused date
Space	Select the focused date
Escape	Close month or year selection views

Code

Implementation
Calendar Props

Live Component Playground

Common Examples

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

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

Date Format

The Calendar component accepts ISO 8601 date strings for value and defaultValue. Prefer date-only strings (for example, "2025-07-02") for predictable calendar date selection.onSelection returns a full ISO datetime string with timezone offset (for example, “2025-07-02T00:00:00.000-07:00”), or undefined when the selection is cleared.Convert to a date-only string (for example, const dateOnly = value?.split("T")[0];) before passing the value to date fields or APIs that expect YYYY-MM-DD.

Example with new Date()

<Calendar defaultValue={new Date().toISOString()} />

Controlling calendar state

Uncontrolled calendars

By default, calendars handle their own state. Use the defaultValue prop to set the initial value of an uncontrolled calendar.

Controlled calendars

Use the value prop to manually control the state of a calendar.

Selecting a date range

Calendar can also be used to select range of dates using range prop.

Calendar focus

By default, the month of selected date or today is shown.

Overriding calendar focus

In the example below, 2024-07-07 is the selected date but June is showing on initial render because of defaultFocusedDate="2024-06-06".

Calendar Timezone

By default, local browser timezone is used. To override local system timezone, defaultTimezone can be used.

Scoping calendar dates

There are two different ways to limit the scope of selectable dates within a calendar.

Min and Max

The minDate and maxDate props can be used to scope the date range selection.

Unavailable dates

You can also pass an array of dates to the unavailable.dates prop to disable selecting specific dates.

<Calendar
  defaultValue="2024-01-15"
  defaultFocusedDate="2024-01-01"
  defaultTimeZone="America/New_York"
  maxDate="2024-12-31"
  minDate="2024-01-01"
  unavailable={{ dates: ["2024-01-20", "2024-01-21"]}}
  value="2024-01-15"
/>

`Calendar` Props

Props marked as BETA are currently only available if you import Calendar from @servicetitan/anvil2/beta.

{ date: string, context: string }[]

BETA Array of date metadata objects to display pips and provide context.

string | null

Uncontrolled focus date. Sets the initially visible month and year.

IanaZone

default:"Local browser timezone"

string | { start?: string; end?: string }

Uncontrolled date value. Object is only accepted when range={true}.

string | null

deprecated

Use defaultFocusedDate instead. focusedDate does not reliably control the initial view and will be removed in a future major release.

Locale

default:"Browser locale"

The locale to use for the calendar.

string

({ month, year }: { month: number, year: number }) => void

BETA Callback when the visible month changes.

(data: { value }) => void

Callback when a date is selected.

boolean

Enable date range selection mode. When true, value and defaultValue accept objects with start and end properties.

"Sunday" | "Monday"

default:"Sunday"

The day of the week to start the calendar on.

{ daysOfWeek?: WeekdayNumbers[]; dates?: string[] }

The days of the week and specific dates that are unavailable.

string | { start?: string; end?: string }

Controlled date value. Object is only accepted when range={true}.

​Anatomy

​Options

​Selection Mode

​Start Day

​Date Restrictions

​Unavailable Dates

​Locale and Timezone

​Behavior

​Selection States

​Navigation

​View Transitions

​Date Constraints

​Usage Guidelines

​Alternatives

​Calendar vs DateField

​How to Use

​Choose single or range selection based on user needs

​Set date boundaries to guide user choices

​Mark unavailable dates to communicate constraints

​Content

​Keyboard Interaction

​Code

​Live Component Playground

​Common Examples

​Date Format

​Example with new Date()

​Controlling calendar state

​Uncontrolled calendars

​Controlled calendars

​Selecting a date range

​Calendar focus

​Overriding calendar focus

​Calendar Timezone

​Scoping calendar dates

​Min and Max

​Unavailable dates

​Calendar Props

Anatomy

Options

Selection Mode

Start Day

Date Restrictions

Unavailable Dates

Locale and Timezone

Behavior

Selection States

Navigation

View Transitions

Date Constraints

Usage Guidelines

Alternatives

Calendar vs DateField

How to Use

Choose single or range selection based on user needs

Set date boundaries to guide user choices

Mark unavailable dates to communicate constraints

Content

Keyboard Interaction

Code

Live Component Playground

Common Examples

Date Format

Example with new Date()

Controlling calendar state

Uncontrolled calendars

Controlled calendars

Selecting a date range

Calendar focus

Overriding calendar focus

Calendar Timezone

Scoping calendar dates

Min and Max

Unavailable dates

`Calendar` Props