CalendarView

A calendar view lets a user view and interact with a calendar that they can navigate by month, year, or decade. A user can select a single date or multiple dates.

import { CalendarView } from "fluent-svelte";

Usage

Controlling Value

Selections made in the calendar can be controlled using the value property, which outputs a Date object or array of Date objects. When the user clicks an item in the calendar, the value property is updated to reflect the selection. value can also be null or undefined to indicate no selection or a selection cleared by the user.

This CalendarView will be initialized with a value of March 3, 2020.

<CalendarView value={new Date(2020, 2, 3)} />

You can also use two-way binding to programatically work with the value of the calendar.

<script>
	import { Button, CalendarView } from "fluent-svelte";

	let value = new Date(); // The current date
</script>

<CalendarView bind:value />

Current value: {value?.toLocaleDateString()}

<Button on:click={() => (value = null)}>Clear Value</Button>

Multiple Selections

CalendarView can also accept more than one value. To initially select multiple dates, pass an array of Date objects to the value property rather than a single Date.

<CalendarView value={[new Date(2022, 2, 3), new Date(2022, 2, 4)]} />

This will render the calendar with March 3 and 4 selected, but as soon as the user attempts to choose another date, the previous selections will be cleared and value will be set back to a single date that the user chooses.

To allow the user to pick multiple dates at once, set the multiple property to true.

<CalendarView multiple value={[new Date(2022, 2, 3), new Date(2022, 2, 4)]} />

Minimum and Maximum Values

You can limit the range of dates that can be selected by the user using the min and max properties. These properties are both Date objects representing the earliest and latest dates that can be selected. If the user attempts to click a date outside of the range, the calendar will not allow the selection.

In this example, the user will only be able to select dates in the year of 2020.

<CalendarView min={new Date(2020, 0, 1)} max={new Date(2020, 11, 31)} />

Localization

Many elements of a calendar need to vary across languages. By default, the calendar automatically localizes itself based on the browser’s navigator.language using the Intl.DateTimeFormat API.

If you only want the calendar to render in a specific locale, you can pass in a locale string to the locale property.

<CalendarView locale="ja-JP" />

Many places additionally have different starting days of the week. The JavaScript Date object starts it’s weeks on Sunday, but you can customize the starting day of the calendar’s week using the weekStart property. weekStart accepts a number between 0 and 6 (zero is sunday, six is saturday).

<!-- Week will start on Monday (1) instead of Sunday (0). -->
<CalendarView weekStart={1} />

“Blackout” Dates

In some cases, it might be desirable to prevent the user from selecting a specific day (or days) in the calendar. This can be done by passing in an array of dates to the blackout property.

In this example, the user will be able to select all dates except for March 7, 2022 and March 9, 2022.

<CalendarView
	value={new Date(2022, 2, 1)}
	blackout={[new Date(2022, 2, 7), new Date(2022, 2, 9)]}
/>

Views

To aid with navigating long ranges of dates, a user can click the CalendarView’s main header to switch the view. This lets the user quickly navigate through days, months, or years.

You can control the current view that the calendar is in using the view property, which can be set to either days, months, or years. Setting the view property will not prevent the user from manually changing the view by clicking the header.

For example, this will start the calendar in the months view:

<CalendarView view="months" />

Item Headers

You can choose display indicator labels for the first day of a month, or first month of a year (depending on the current view) by setting the headers property.

• When in days view, the first day of a given month will have a header with the month’s name above it.
• When in months view, the first month of a given year will have the year labeled above it.

<CalendarView headers />

Component API

Props

Slots

Events

Forwarded Events

Dispatched Events