Calendar

A full featured calendar component with month, week, day, and timeline views. Purely presentational, this component requires the consumer to fetch their own data

Overview

  • Available since: Quebec
  • A11Y: WCAG 2.1 AA

Anatomy

Learn about the individual parts of calendar.

Calendar header

anatomy of calendar header
  1. Content slot (optional): Slot for placing optional actions or content
  2. New Button (optional): Creates a new event on the Calendar
  3. Date selector: Provides navigation to the previous or next time period; enables users to quickly select a specific date or to navigate to the current date.
  4. Middle content slot (optional): Additional slot for placing optional actions or content
  5. Time zone selector: Available when the user selects a time zone other than the default in the preferences menu; lets the user select a time zone from a configured list
  6. View selector (optional): Allows selection of views from a configured list
  7. Content slot (optional): Slot for placing optional actions or content
  8. Settings menu: Provides access to the keyboard shortcuts

Calendar grid

anatomy of the calendar grid
  1. Current day indicator: Indicates the current date
  2. Selected day indicator: Indicates the selected date
  3. Event: An event with a start and end date/time
  4. Current time indicator: Indicates the current time

Timeline grid

anatomy of the calendar timeline grid
  1. Content slot (optional): Contains optional actions or content
  2. Current time indicator: Indicates the current time
  3. Increase column width: Increases the width of the column
  4. Reset column width: Displays the current level of the column width. Reverts to the default width when clicked.
  5. Decrease column width: Decreases the width of the column
  6. Collapse column width control: Collapses the column width control
  7. Event: An event with a start and end date/time
  8. Row context: Displays the context and assigned user for the scheduled events shown
  9. Grouped row (optional): Can expand/collapse rows below and display rollup/summary data
  10. Summary row (optional): Can display rollup/summary data for the rows below

Contextual side panel

anatomy of the calendar contextual side panel
  1. Contextual side panel (optional): Displays cards for all the agenda items in the selected view and additional configured widgets
  2. Event card: Displays details about an event within the agenda side panel display

Subcomponents

See usage guidance for button

See usage guidance for button bare

See usage guidance for dropdown

See usage guidance for button iconic

See usage guidance for popover

See usage guidance for heading

See usage guidance for card

See usage guidance for mini calendar

Usage

Use a calendar on a page where a user needs to see events with a scheduled start and end time. Some examples could be on-call schedules, agent shifts, recurring meetings, or scheduled changes.

Configurations

Learn how to customize calendar by configuring the available properties.

Views

You can configure different calendar views. The traditional calendar views of Day, Week, and Month are available. You can also select Timeline – Day and Timeline – Week to display scheduled events for a collection of contexts like agents or records.

week view of the calendar

Week view

week view of the calendar

Month view

week view of the calendar

Day view

week view of the calendar

Timeline day view

week view of the calendar

Timeline week view

week view of the calendar

Timeline extended week / month view

Contextual side panel

You can hide or display the contextual side panel for each selected calendar view. Add content to your side panel that includes information appropriate to the calendar, such as work schedules or time off requests. By default, there is an agenda list available that lists events chronologically as cards for the selected date and by context, if applicable. For days with numerous scheduled events, the agenda list is the only way to access all the events for the month view. For this reason, you shouldn't disable the agenda list for the month view.

schedules in the calendar side panel

Right click action

You can configure events to have right click action that opens a menu and enables users to take actions in less steps.

Right click action on the contextual side panel

Right click action

New event actions

You can configure the New button to appear that enables users to create a new calendar event. If you need to create more detailed events for your application, you can disable the New button and insert a custom button in the content slot to the left side.

new button of the calendar

Event selection popover

You can configure a popover to display when the user selects an event. The popover contains a single slot, so the content, layout, and actions available in the event popover are all configurable.

contents of event popover

Multiple event selection

The user can select multiple events by holding the Shift or CMD button and selecting the events. The selection summary in the contextual side panel displays the selected events.

contents of event popover

Event height

By default, the height of calendar events is 20 pixels. You can configure the initial height or dynamically change the height of all the events. The event height can be between 20 pixels and 100 pixels unless you change using the minimum and maximum height values.

Minimum

By default, the height of events is 50 pixels; the minimum possible height is 24.

Maximum

By default, the maximum height of events is 100 pixels, and the maximum height is configurable to any limit.

Timeline grouped rows

You can group the context list in a Timeline view by different values. Depending on your use case, you might group agents by their assignment groups.

grouped row on calendar timeline

Timeline summary row

You can use a template to insert content into a Summary row in Timeline views. An example of this might be the count of current agents scheduled vs. the forecasted demand for a particular time slot.

summary row on calendar timeline

Timeline month representation

You can see a month-wise representation of events in the timeline view.

summary row on calendar timeline

Timeline day/week grid width

You can disable horizontal scrolling when the content overflows the container width. This causes the grid columns to shrink to fit the available width.

Timeline column width control

Timeline column width control is enabled by default and is displayed at the bottom-right corner in the view. To increase or decrease the column width, the user selects the width control buttons. To reset the column width to its default (100%), the user selects the area displaying the current width level.

Design recommendations

Learn how to apply calendar in your design.

full page calendar for better views
Do

Display calendar on a full screen so that the user can see all information and controls easily.

calendar that is too small on the page
Don’t

Avoid using calendar in a small space; it can make it challenging for the user to access all events and controls.

using a single calendar per page
Do

Use only a single calendar per page to avoid confusion.

improper use of multiple calendars on a page
Don’t

Avoid using more than 1 calendar on a page because it makes it difficult for users to view the data and understand how the calendars are related.

calendar with supporting functionality in the side panel
Do

Add custom functionality to the embedded side panel to support the needs and context of the calendar users.

using too many additional components on a page with calendar
Don’t

Avoid adding additional components on the page for functions that can exist in the side panel. This makes it difficult for the user to access all events and controls.

UI text guidelines

These are some recommendations for using text within calendar:

  • Keep all text labels short and concise
  • Slot content should be descriptive and concise.

Behavior

Learn how calendar behaves when the display changes or a user interacts with the component.

Left column cell states

Cells in the left most column behave as buttons with different states.
States included are default, focus, hover, pressed, selected, selected (hover), selected (focus), selected (disabled), and selected (pressed).

Default

Default state of the left column cell

Focus

Focus state of the left column cell

Hover

Hover state of the left column cell

Pressed

Pressed state of the left column cell

Selected

Selected state of the left column cell

Selected (hovered)

Hover state of a selected cell in the left column

Selected (focused)

Focused state of a selected cell in the left column

Selected (disabled)

Disabled state of a selected cell in the left column

Selected (pressed)

hover state for an agenda event

Agenda event hover

Hovering over an agenda event highlights the card and displays a tooltip.

hover state for an agenda event

Calendar grid event hover

Hovering over a calendar grid event highlights the event and displays a tooltip. The user can resize the event container vertically to display hidden content by dragging the handle (three dots) at the bottom of the container.

hover state for a calendar event

Timeline grid event hover

Hovering over a timeline grid event highlights the event and displays a tooltip. The user can resize the event container horizontally to display hidden content with the drag handle at the right side of the container.

hover state for a timeline event

Timeline context selected

Selecting a context row highlights the selection.

selected state for a timeline context

In this example, collapse is used within a content tree. When the user selects 'Show More,' the remaining nodes appear.

Day selected

When the user selects a day, the date appears inside a solid circle.

selected state for a day

Week states for extended timelines

Extended multi-week, month, and year timelines’ column headers have different states. States included are default, focus, hover, pressed, selected, selected (hover), selected (focus), selected (pressed), and selected (disabled).

State Normal
Default now-calendar
Focus now-calendar
Hover now-calendar
Pressed now-calendar
Selected now-calendar
Selected (hover) now-calendar
Selected (focus) now-calendar
Selected (pressed) now-calendar
Selected (disabled) now-calendar

Responsive behaviors

Learn how calendar responds to changes in a container or display.

Calendar Day/Week/Work Week grid

These grids resize as the container shrinks. All grids have a vertical scrollbar.

Month grid

This grid resizes proportionally as the container shrinks, so that the entire month is visible without scrolling.

Month view event overflow

If more events are present than can be displayed, the X more disclosure control appears at the bottom of the cell, indicating how many events are hidden. The user selects this control to show the hidden events. All events become visible with a vertical scrollbar in the agenda side panel display. If the side panel is closed, clicking the X more control opens the side panel.

disclosure control showing number of hidden events

Timeline Day/Week grid

By default, the timeline day and week view grids display horizontal and vertical scrollbars when the content overflows the container. If horizontal scrolling is disabled, the grid columns shrink to fit the available width.

vertical scroll on timeline grid

Interactions

Learn how calendar responds when a user interacts with it.

Shifting Columns

Users can view the previous or next date range (week, month, and year) by clicking the left and right arrow buttons on the each side of the column header row.

mini calendar for setting the calendar view date range
  1. Left arrow: When clicked, shifts the calendar left to show the previous week, month, or year
  2. Right arrow: When clicked, shifts the calendar right to show the next week, month, or year

If there are no additional columns to show, new columns are added.

mini calendar for setting the calendar view date range

Mini calendar

When the user selects the current date range, the mini calendar opens. Selecting a date closes the mini calendar and sets the appropriate date range in the current view.

mini calendar for setting the calendar view date range

Time zone picker

The time zone selector opens the time zone menu, allowing the user to select a time zone for their calendar view. Changing time zone resets the view of the calendar grid and events to reflect the new time zone.

picker for the setting calendar view time zone

View selector

The view selector opens the view menu, allowing the user to select a new view from the configured options. Selecting a new view resets the view to the date range containing the currently selected date.

picker for the setting calendar view

Settings

The gear icon opens the settings menu, allowing the user to access the keyboard shortcuts. An alternative method is to press the forward slash ( / ) key.

settings menu of keyboard shortcuts

Selected event popover

Selecting an event on either the calendar grid or in the agenda side panel displays the event popover. The content and interactions available in this popover are configured separately for each calendar by the consuming application and may differ.

contents of event popover

Day selection

Selecting a specific day on the calendar sets the selected date for the agenda list and opens the side panel, if it's closed.

selecting days for the agenda list

Month view cell

Selecting X more on the calendar sets the selected date for the agenda list and opens the side panel, if it's closed.

disclosure control selection

Side panel

Selecting an icon in the side bar displays the side panel and sets the content of the panel to that of the selected icon. If the currently selected icon is selected again, the panel collapses. If the panel is collapsed when the icon is clicked, it expands.

expanded side panel with selected information

Controls in the side panel enable the user to collapse the panel to provide more room for the calendar grid.

side panel hidden in a calendar

Truncation

When text in some calendar elements exceeds the width of the container or content area, the text truncates with an ellipsis, and a tooltip shows the full content on hover.

Agenda event

truncated content in an agenda event

Timeline event

truncated content in a timeline grid

In this example, a timeline event truncates with a tooltip when the cell is too small to display all the content.

Usability

Calendar complies with all internationalization and accessibility requirements.

Internationalization

When the display translates to a right-to-left (RTL) language, the orientation of all elements within the calendar flips, including the side panel and its contents.

orientation of calendar for right-to-left languages

Accessibility

Learn how to access the actionable elements of calendar through keyboard interactions and screen readers.

Calendar tab order

tab order of calendar component

Keyboard interactions

You can access the actionable elements of calendar with these keyboard keys: In the Day and Week views, when a user increases the browser zoom level, the component resizes and reflows automatically to fit the screen without losing information. The component supports zoom levels up to 400%.

  • Tab: Navigates through actionable items in the calendar in the specified order
  • Shift + Tab: Navigates through actionable items in reverse order
  • Enter: Interacts with subcomponents, such as the date selector
  • Arrows: If events are focused, arrow keys shifts the focus to the timeslots underneath those events and user can further move the focus within calendar grid using the arrow keys

When the calendar grid is focused, users can access the actionable elements with these keyboard keys:

  • /: Toggle keyboard shortcuts legend
  • F: Set focus on calendar grid
  • ESC: Close popover
  • Enter: Select focused item
  • T: Move to today's date
  • P: Move to previous time range
  • N: Move to next time range
  • Arrow keys: Move in any direction within the selected timeslot/calendar
  • E: Select next event
  • Shift + E: Select previous event
  • D: Select next date
  • Shift + D: Select previous date
  • M: Select next marked span
  • Shift + M: Select previous marked span
  • S: Select next section/row
  • Shift + S: Select previous section/row
  • 1: Day view
  • 2: Work Week view
  • 3: Week view
  • 4: Month view
  • 5: Day view (Timeline)
  • 6: Week view (Timeline)

Reflow

In the Day and Week views, when a user increases the browser zoom level, the component resizes and reflows automatically to fit the screen without losing information. The component supports zoom levels up to 400%.