Range Calendar

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

range-calendar.ts

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

export default golemForm().create({
  form: [
    {
      kind: 'input',
      type: 'rangeCalendar',
      path: 'vacationDates',
    },
  ],
});

range-calendar.json

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

Props

Use these props to customize your Range Calendar component. 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

Note

A label is required for the hint to be displayed.

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

range-calendar.ts

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

export default golemForm().create({
  form: [
    {
      kind: 'input',
      type: 'rangeCalendar',
      path: 'vacationDates',
      props: {
        hint: 'Please select the start and end dates for your vacation',
      },
      label: 'Vacation Dates',
    },
  ],
});

range-calendar.json

{
  "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.

range-calendar.ts

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

export default golemForm().create({
  form: [
    {
      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',
      },
    },
  ],
});

range-calendar.json

{
  "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.

range-calendar.ts

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

export default golemForm().create({
  form: [
    {
      kind: 'input',
      type: 'rangeCalendar',
      path: 'vacationDates',
      props: {
        numberOfMonths: 2,
      },
    },
  ],
});

range-calendar.json

{
  "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.

range-calendar.ts

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

export default golemForm().create({
  form: [
    {
      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',
          },
        ],
      },
    },
  ],
});

range-calendar.json

{
  "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.

range-calendar.ts

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

export default golemForm().create({
  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',
      },
    },
  ],
});

range-calendar.json

{
  "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.

range-calendar.ts

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

export default golemForm().create({
  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',
      },
    },
  ],
});

range-calendar.json

{
  "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 component 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 Component in case you want to use your CSS styles.

range-calendar-anatomy.html

<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>