Range Calendar

Range Calendar widgets are Input Fields that allow the user to visualize and select an inclusive date range (start date and end date).

import { gui } from '@golemui/gui-shared';

export default [
  gui.inputs.rangeCalendar('vacationDates'),
];

{
  "form": [
    {
      "uid": "",
      "kind": "input",
      "type": "rangeCalendar",
      "path": "vacationDates"
    }
  ]
}

Props

Use these props to customize your Range Calendar widget. Range Calendars share all properties with standard Calendars.

prop	type	description
`hint`	string	A description to display below the range calendar
`minDate`	string	Minimum allowable date in ISO format
`maxDate`	string	Maximum allowable date in ISO format
`numberOfMonths`	number	Number of months to display simultaneously. Defaults to 2 for range calendars
`disabledRanges`	array	Array of objects (`{ start: string, end?: string }`) defining disabled date ranges
`prevMonthAriaLabel`	string	Accessible label for the previous month navigation button
`nextMonthAriaLabel`	string	Accessible label for the next month navigation button
`removePillAriaLabel`	string	Accessible label for the remove button on date range pills

Hint

Use the property hint to add a description to the date range selection.

import { gui } from '@golemui/gui-shared';

export default [
  gui.inputs.rangeCalendar('vacationDates', {
    hint: 'Please select the start and end dates for your vacation',
    label: 'Vacation Dates',
  }),
];

{
  "form": [
    {
      "uid": "",
      "kind": "input",
      "type": "rangeCalendar",
      "path": "vacationDates",
      "props": {
        "hint": "Please select the start and end dates for your vacation"
      },
      "label": "Vacation Dates"
    }
  ]
}

Min and Max Dates

Use the properties minDate and maxDate to specify the boundaries for selectable dates.

import { gui } from '@golemui/gui-shared';

export default [
  gui.inputs.rangeCalendar('vacationDates', {
    minDate: '2024-06-01T00:00:00.000Z',
    maxDate: '2024-08-31T23:59:59.999Z',
  }),
];

{
  "form": [
    {
      "uid": "",
      "kind": "input",
      "type": "rangeCalendar",
      "path": "vacationDates",
      "defaultValue": [{ "start": "2024-06-21" }],
      "props": {
        "minDate": "2024-06-01T00:00:00.000Z",
        "maxDate": "2024-08-31T23:59:59.999Z"
      }
    }
  ]
}

Number of Months

Use the property numberOfMonths to display multiple months side-by-side to ease selection of larger spans.

import { gui } from '@golemui/gui-shared';

export default [
  gui.inputs.rangeCalendar('vacationDates', {
    numberOfMonths: 2,
  }),
];

{
  "form": [
    {
      "uid": "",
      "kind": "input",
      "type": "rangeCalendar",
      "path": "vacationDates",
      "props": {
        "numberOfMonths": 2
      }
    }
  ]
}

Disabled Ranges

Use the property disabledRanges to define dates which cannot be highlighted as part of a range.

import { gui } from '@golemui/gui-shared';

export default [
  gui.inputs.rangeCalendar('vacationDates', {
    disabledRanges: [
      {
        start: '2024-07-04T00:00:00.000Z',
        end: '2024-07-07T23:59:59.999Z',
      },
    ],
  }),
];

{
  "form": [
    {
      "uid": "",
      "kind": "input",
      "type": "rangeCalendar",
      "path": "vacationDates",
      "defaultValue": [{ "start": "2024-07-21", "end": "2024-07-25" }],
      "props": {
        "disabledRanges": [
          {
            "start": "2024-07-04T00:00:00.000Z",
            "end": "2024-07-07T23:59:59.999Z"
          }
        ]
      }
    }
  ]
}

Custom Icons

Use prevMonthIcon, nextMonthIcon, prevMonthAriaLabel and nextMonthAriaLabel to customize the navigation buttons.

import { gui } from '@golemui/gui-shared';

export default [
  gui.inputs.rangeCalendar('dates', {
    prevMonthIcon: 'chevron_left',
    nextMonthIcon: 'chevron_right',
    prevMonthAriaLabel: 'Go to previous month',
    nextMonthAriaLabel: 'Go to next month',
    label: 'Custom Icons Range Calendar',
    uid: 'range-calendar-icons',
  }),
];

{
  "form": [
    {
      "uid": "range-calendar-icons",
      "kind": "input",
      "type": "rangeCalendar",
      "path": "dates",
      "label": "Custom Icons Range Calendar",
      "props": {
        "prevMonthIcon": "chevron_left",
        "nextMonthIcon": "chevron_right",
        "prevMonthAriaLabel": "Go to previous month",
        "nextMonthAriaLabel": "Go to next month"
      }
    }
  ]
}

Aria Labels

Use prevMonthAriaLabel, nextMonthAriaLabel and removePillAriaLabel to provide accessible labels for the navigation buttons and the remove button on date range pills.

import { gui } from '@golemui/gui-shared';

export default [
  gui.inputs.rangeCalendar('dates', {
    prevMonthAriaLabel: 'Go to previous month',
    nextMonthAriaLabel: 'Go to next month',
    removePillAriaLabel: 'Remove date range',
    label: 'Range Calendar with Aria Labels',
    uid: 'range-calendar-aria-labels',
  }),
];

{
  "form": [
    {
      "uid": "range-calendar-aria-labels",
      "kind": "input",
      "type": "rangeCalendar",
      "path": "dates",
      "label": "Range Calendar with Aria Labels",
      "props": {
        "prevMonthAriaLabel": "Go to previous month",
        "nextMonthAriaLabel": "Go to next month",
        "removePillAriaLabel": "Remove date range"
      }
    }
  ]
}

Styling

Range Calendars can be styled as explained in the Styling Guide. They inherit all Calendar widget styles along with specialized range highlighting rules.

CSS Variables

Following you will find a list with the CSS Variables and a quick description of what you will style.

CSS Variable	Description
`--gui-radius-md`	Calendar container base radius
`--gui-radius-range`	Border radius applied to the start and end of a selected range (calculated as double `radius-md`)
`--gui-bg-default`	Calendar container background color
`--gui-border-default`	Default border color and cell hover border color
`--gui-space-3`	Internal padding
`--gui-calendar-change-month-button-width`	Width of the next/prev buttons
`--gui-calendar-change-month-button-height`	Height of the next/prev buttons
`--gui-text-default`	Default text and focus border color
`--gui-text-secondary`	Day button hover background color
`--gui-intent-primary-active`	”Today” border highlight color
`--gui-intent-primary`	Selected range and selected day background color
`--gui-bg-disabled`	Disabled day background color

Anatomy

This is the anatomy of the Range Calendar Widget in case you want to use your CSS styles.

<gui-range-calendar>
  <label for="fieldUid" id="fieldUid_calendar_label">
    Label
    <div class="gui-calendar__hint" id="fieldUid_hint">Hint</div>
  </label>

  <div class="gui-widget">
    <div class="gui-calendar-input" role="group" aria-labelledby="fieldUid_calendar_label">

      <!-- Pills -->
      <div class="gui-range-calendar__pills-wrapper gui-range-calendar--start-shadow gui-range-calendar--end-shadow">
        <div class="gui-range-calendar__pills" role="list">
          <span class="gui-sentinel gui-sentinel__start"></span>
          <div class="gui-range-calendar__pill" role="listitem" tabindex="0" aria-label="Remove date range 03/01/2024 - 03/03/2024">
            <span class="gui-range-calendar__pill-text">03/01/2024 - 03/03/2024</span>
            <button type="button" class="gui-range-calendar__pill-remove" tabindex="-1">&times;</button>
          </div>
          <span class="gui-sentinel gui-sentinel__end"></span>
        </div>
      </div>

      <div class="gui-calendar__container">
        <button type="button" class="gui-button gui-calendar__month-button gui-calendar__month-button--prev" aria-label="Previous month">&lt;</button>

        <div class="gui-calendar__months-grid">
          <div class="gui-calendar__panel">
            <header class="gui-calendar__header">
              <h2>
                <span class="gui-calendar__month-name">March</span>
                <button type="button" class="gui-calendar__year-selector" aria-expanded="false" aria-label="Select year">
                  <span class="gui-calendar__year-value">2024</span>
                  <span class="gui-calendar__year-arrow" aria-hidden="true">▾</span>
                </button>
              </h2>
            </header>

            <div class="gui-calendar__days-grid" role="grid">
              <div role="row" class="gui-calendar__rows">
                <span class="gui-calendar__weekday" role="gridcell">Su</span>
                <span class="gui-calendar__weekday" role="gridcell">Mo</span>
                <span class="gui-calendar__weekday" role="gridcell">Tu</span>
                <span class="gui-calendar__weekday" role="gridcell">We</span>
                <span class="gui-calendar__weekday" role="gridcell">Th</span>
                <span class="gui-calendar__weekday" role="gridcell">Fr</span>
                <span class="gui-calendar__weekday" role="gridcell">Sa</span>
              </div>
              <div role="row" class="gui-calendar__rows">
                <button type="button" role="gridcell" class="gui-calendar__day-button other-month" tabindex="-1" disabled aria-selected="false">25</button>
                <button type="button" role="gridcell" class="gui-calendar__day-button range-start" tabindex="0" aria-selected="true">1</button>
                <button type="button" role="gridcell" class="gui-calendar__day-button in-range" tabindex="-1" aria-selected="true">2</button>
                <button type="button" role="gridcell" class="gui-calendar__day-button range-end" tabindex="-1" aria-selected="true">3</button>
                <button type="button" role="gridcell" class="gui-calendar__day-button today" tabindex="-1" aria-selected="false">4</button>
                <button type="button" role="gridcell" class="gui-calendar__day-button" tabindex="-1" aria-selected="false">5</button>
                <button type="button" role="gridcell" class="gui-calendar__day-button" tabindex="-1" aria-selected="false">6</button>
              </div>
            </div>
          </div>
        </div>

        <button type="button" class="gui-button gui-calendar__month-button gui-calendar__month-button--next" aria-label="Next month">&gt;</button>
      </div>
    </div>
  </div>

  <ul class="gui-validator" id="fieldUid_errors">
    <li class="gui-validator__error" role="alert">Error message</li>
  </ul>
</gui-range-calendar>