CalendarView

Edit This Page

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";
Sun Mon Tue Wed Thu Fri Sat

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.

Sun Mon Tue Wed Thu Fri Sat
Current value: 12/5/2022
<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.

Sun Mon Tue Wed Thu Fri Sat
<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.

Sun Mon Tue Wed Thu Fri Sat
<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).

Mon Tue Wed Thu Fri Sat Sun
<!-- 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.

Sun Mon Tue Wed Thu Fri Sat
<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.


Sun Mon Tue Wed Thu Fri Sat


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.
Sun Mon Tue Wed Thu Fri Sat
<CalendarView headers />
No Headers Headers

Component API

API docs automatically generated by sveld and vite-plugin-sveld.

Props

NameTypeDefaultDescription
locale any undefined Locale code used for specifying the language of the calendar. If unset, the locale will be automatically inferred from `navigator.language`.
multiple boolean false Determines if multiple dates can be manually selected by the user.
headers boolean false Controls whether header text will be shown above items representing the first day of a month or the first month of a year.
value any null The currently selected calendar date(s).
blackout any undefined Array of specifically excluded dates that cannot be selected by the user.
min any undefined The minimum date that can be manually selected by the user.
max any undefined The maximum date that can be manually selected by the user.
view string "days" The selection view that the calendar will start in. Views can be manually changed by the user when clicking the calendar's header.
weekStart number 0 Number representing the day that the calendar week starts on. 0 is sunday, 6 is saturday.
element null | HTMLDivElement null Obtains a bound DOM reference to the calendar's outer container element.

Slots

None

Events

Forwarded Events

None

Dispatched Events

NameDetail
change None