Calendar

Guidelines
React API Reference
Blazor API Reference

The Calendar component provides an intuitive interface for users to select dates, navigate between months and years, and view date ranges. It supports both single date selection and date range selection, with customizable display options and accessibility features.

Guidance

Aspect	Best Practice
Usage	Use calendars for date input, scheduling, event planning, or any scenario requiring date selection.
Content	Display clear month/year navigation, properly formatted dates, and intuitive selection states.
Behavior	Provide keyboard navigation, clear visual feedback for selected dates, and smooth transitions between months.
Modes	Choose single selection for individual dates, range selection for date spans, or multiple selection for non-contiguous dates.
Navigation	Include month/year dropdowns or navigation arrows to help users quickly move between time periods.
Examples	Booking systems, event schedulers, date filters, or form date inputs.

Best Practices

Clear Selection States: Use distinct visual styling for selected dates, today’s date, and hover states to guide user interaction.
Keyboard Navigation: Ensure full keyboard accessibility with arrow keys for navigation and Enter/Space for selection.
Range Selection: For date ranges, provide clear visual indication of start date, end date, and the range between them.
Outside Days: Consider showing days from adjacent months to provide context, but style them differently to avoid confusion.
Responsive Design: Ensure the calendar works well on both desktop and mobile devices with appropriate touch targets.

Do’s and Don’ts

Do

Provide clear visual feedback for selected dates.
Use consistent date formatting throughout.
Include keyboard navigation support.
Show today’s date prominently.

Don't

Make date selection targets too small for touch.
Use confusing color schemes for different states.
Forget to handle edge cases like leap years.
Overcomplicate the interface with too many options.

Additional Guidance

Accessibility: Ensure proper ARIA labels, keyboard navigation, and screen reader support for all calendar interactions.
Psychological Impact:
- Visual Hierarchy: Clear month/year headers and date organization help users orient themselves in time.
- Cognitive Load: Familiar calendar layout reduces mental effort required to understand and use the interface.
- Confidence: Clear selection states and navigation options give users confidence in their date choices.

Import

import { Calendar } from '@strongtie/design-system/calendar';

Usage

<Calendar
  mode="single"
  selected={date}
  onSelect={setDate}
/>

`<Calendar>` Props

mode

"single" | "multiple" | "range"

default:"\"single\""

The selection mode for the calendar. Single allows one date, multiple allows multiple non-contiguous dates, and range allows selecting a date range.

selected

Date | Date[] | DateRange | undefined

The currently selected date(s). Type depends on the mode prop.

onSelect

(date: Date | Date[] | DateRange | undefined) => void

Callback fired when a date is selected. The parameter type depends on the mode prop.

classNames

Partial<ClassNames>

Object to customize individual element class names within the calendar.

showOutsideDays

boolean

default:"true"

Whether to show days from adjacent months in the calendar grid.

captionLayout

"label" | "dropdown"

default:"\"label\""

Layout mode for the month/year caption. “label” shows static text, “dropdown” shows interactive dropdowns.

formatters

Partial<Formatters>

Custom formatters for displaying dates and other calendar elements.

components

Partial<Components>

Custom components to override default calendar elements.

defaultMonth

Date

The month to display by default when the calendar is first rendered.

numberOfMonths

number

default:"1"

Number of months to display simultaneously.

disabled

boolean | Date | Date[] | DateRange | ((date: Date) => boolean)

Dates that should be disabled and not selectable.

hidden

boolean | Date | Date[] | DateRange | ((date: Date) => boolean)

Dates that should be hidden from the calendar.

modifiers

Record<string, boolean | Date | Date[] | DateRange | ((date: Date) => boolean)>

Custom modifiers to apply styling or behavior to specific dates.

fromDate

Date

The earliest date that can be selected.

toDate

Date

The latest date that can be selected.

fromMonth

Date

The earliest month that can be navigated to.

toMonth

Date

The latest month that can be navigated to.

Styling Classes

The component applies the following CSS classes:

calendar - Root calendar container
calendar-months - Container for month displays
calendar-month - Individual month container
calendar-nav - Navigation controls container
calendar-button - Navigation buttons
calendar-month-caption - Month/year caption
calendar-table - Calendar grid table
calendar-day - Individual day cells
calendar-day-button - Day selection buttons
calendar-today - Today’s date styling
calendar-selected - Selected date styling
calendar-range-start - Range start date styling
calendar-range-end - Range end date styling
calendar-range-middle - Range middle dates styling
calendar-outside - Outside month days styling
calendar-disabled - Disabled date styling

Usage Examples

function SingleDateExample() {
  const [date, setDate] = React.useState<Date | undefined>(new Date())

  return (
    <Calendar
      mode="single"
      selected={date}
      onSelect={setDate}
    />
  )
}

For more examples, visit the Storybook.

Example

<StudsDatePicker @bind-Value="selectedDate"
                 TValue="DateTime?"
                 Inline="true"
                 />

@code {
    DateTime? selectedDate = DateTime.Now;
}

StudsCalendar is a StudsDatePicker with the paramater Inline set to true. See StudsDatePicker for more information.For more examples, visit the Storybook.

Getting Started

Foundations

Components

Integration Guides

Content

Guidance

Best Practices

Do’s and Don’ts

Do

Don't

Additional Guidance

`<Calendar>` Props

Styling Classes

Usage Examples

Getting Started

Foundations

Components

Integration Guides

Content

​Guidance

​Best Practices

​Do’s and Don’ts

Do

Don't

​Additional Guidance

​<Calendar> Props

​Styling Classes

​Usage Examples

Guidance

Best Practices

Do’s and Don’ts

Additional Guidance

`<Calendar>` Props

Styling Classes

Usage Examples