Date picker

The guideline content on this page is synced with Figma and can be used as a source of truth. Open in Figma

Date pickers allow users to choose a date or a range of dates.

Anatomy

Label
Mandatory (optional)
Container
Helper text
Help label
Info icon (optional)

States

Enabled
Hover
Selected
Error
Error focused
Disabled
Read only
Focused

Example
HTML

Label

Change this to a short description

Label

Change this to a short description

Label

Change this to a short description

Label

Change this to a short description

Label

Change this to a short description

Label

Change this to a short description

Label

Change this to a short description

Label

Change this to a short description

development/documentation/docs/datepicker/examples/states.html

<div class="d-flex flex-wrap gap-24">
	<!-- 1. Enabled -->
	<div class="form-group required docs-form-state-width">
		<span class="docs-state-number" aria-hidden="true">1</span>
		<label for="dpStateEnabled">Label</label>
		<div class="datepicker">
			<div class="control">
				<input type="text" class="form-control" id="dpStateEnabled" placeholder="YYYY-MM-DD" aria-describedby="dpStateEnabledHelp" required>
				<button type="button" class="icon" aria-label="Open date picker"></button>
			</div>
		</div>
		<span id="dpStateEnabledHelp" class="help-block">Change this to a short description</span>
	</div>

	<!-- 2. Hover -->
	<div class="form-group required docs-form-state-width">
		<span class="docs-state-number" aria-hidden="true">2</span>
		<label for="dpStateHover">Label</label>
		<div class="datepicker">
			<div class="control">
				<input type="text" class="form-control hover" id="dpStateHover" placeholder="YYYY-MM-DD" aria-describedby="dpStateHoverHelp" required>
				<button type="button" class="icon" aria-label="Open date picker"></button>
			</div>
		</div>
		<span id="dpStateHoverHelp" class="help-block">Change this to a short description</span>
	</div>

	<!-- 3. Selected — real Buefy datepicker that opens on input click and closes when a date is selected (default behaviour). -->
	<div class="form-group required docs-form-state-width docs-form-group-buefy-datepicker">
		<span class="docs-state-number" aria-hidden="true">3</span>
		<label for="dpStateSelectedInput">Label</label>
		<div id="appStateSelected">
			<b-datepicker
				id="dpStateSelectedInput"
				aria-describedby="dpStateSelectedHelp"
				v-model="selectedDate"
				editable
				icon="calendar"
				:first-day-of-week="1"
				:nearby-selectable-month-days="true"
				:month-names="month_names"
				:day-names="day_names"
				:show-week-number="true"
				:date-formatter="dateFormatter"
				:date-parser="dateParser"
				placeholder="YYYY-MM-DD">
			</b-datepicker>
		</div>
		<span id="dpStateSelectedHelp" class="help-block">Change this to a short description</span>
	</div>

	<!-- 4. Error -->
	<div class="form-group required has-error docs-form-state-width">
		<span class="docs-state-number" aria-hidden="true">4</span>
		<label for="dpStateError">Label</label>
		<div class="datepicker">
			<div class="control">
				<input type="text" class="form-control" value="2026-04-15" id="dpStateError" aria-describedby="dpStateErrorHelp" required>
				<button type="button" class="icon" aria-label="Open date picker"></button>
			</div>
		</div>
		<span id="dpStateErrorHelp" class="help-block"><span aria-hidden="true" class="spirisicon spirisicon-sm spirisicon-filled spirisicon-alert"></span> Change this to a short description</span>
	</div>

	<!-- 5. Error focused -->
	<div class="form-group required has-error docs-form-state-width">
		<span class="docs-state-number" aria-hidden="true">5</span>
		<label for="dpStateErrorFocused">Label</label>
		<div class="datepicker">
			<div class="control">
				<input type="text" class="form-control focus" value="2026-04-15" id="dpStateErrorFocused" aria-describedby="dpStateErrorFocusedHelp" required>
				<button type="button" class="icon" aria-label="Open date picker"></button>
			</div>
		</div>
		<span id="dpStateErrorFocusedHelp" class="help-block"><span aria-hidden="true" class="spirisicon spirisicon-sm spirisicon-filled spirisicon-alert"></span> Change this to a short description</span>
	</div>

	<!-- 6. Disabled -->
	<div class="form-group required docs-form-state-width">
		<span class="docs-state-number" aria-hidden="true">6</span>
		<label for="dpStateDisabled">Label</label>
		<div class="datepicker">
			<div class="control">
				<input type="text" class="form-control" id="dpStateDisabled" placeholder="YYYY-MM-DD" aria-describedby="dpStateDisabledHelp" disabled>
				<button type="button" class="icon" aria-label="Open date picker" disabled tabindex="-1"></button>
			</div>
		</div>
		<span id="dpStateDisabledHelp" class="help-block">Change this to a short description</span>
	</div>

	<!-- 7. Read only -->
	<div class="form-group required docs-form-state-width">
		<span class="docs-state-number" aria-hidden="true">7</span>
		<label for="dpStateReadonly">Label</label>
		<div class="datepicker">
			<div class="control">
				<input type="text" class="form-control" value="2026-04-15" id="dpStateReadonly" aria-describedby="dpStateReadonlyHelp" readonly>
				<button type="button" class="icon" aria-label="Open date picker" disabled tabindex="-1"></button>
			</div>
		</div>
		<span id="dpStateReadonlyHelp" class="help-block">Change this to a short description</span>
	</div>

	<!-- 8. Focused -->
	<div class="form-group required docs-form-state-width">
		<span class="docs-state-number" aria-hidden="true">8</span>
		<label for="dpStateFocused">Label</label>
		<div class="datepicker">
			<div class="control">
				<input type="text" class="form-control focus" id="dpStateFocused" placeholder="YYYY-MM-DD" aria-describedby="dpStateFocusedHelp" required>
				<button type="button" class="icon" aria-label="Open date picker"></button>
			</div>
		</div>
		<span id="dpStateFocusedHelp" class="help-block">Change this to a short description</span>
	</div>
</div>

Label

A label is mandatory for all text fields and should describe the field's purpose. Labels are included by default. If another element (such as a section title) already serves as a clear description, the default label can be visually hidden.

Example
HTML

Label

Change this to a short description

development/documentation/docs/datepicker/examples/label.html

<div class="form-group required docs-form-state-width">
	<label for="dpLabelDefault">Label</label>
	<div class="datepicker">
		<div class="control">
			<input type="text" class="form-control" id="dpLabelDefault" placeholder="YYYY-MM-DD" aria-describedby="dpLabelDefaultHelp" required>
			<button type="button" class="icon" aria-label="Open date picker"></button>
		</div>
	</div>
	<span id="dpLabelDefaultHelp" class="help-block">Change this to a short description</span>
</div>

Helper text

Helper text communicates requirements and disclaimers below the field. An error message will always replace the helper text when a field validation error is triggered.

Example
HTML

Label

Change this to a short description

development/documentation/docs/datepicker/examples/helper-text.html

<div class="form-group required docs-form-state-width">
	<label for="dpHelperTextDefault">Label</label>
	<div class="datepicker">
		<div class="control">
			<input type="text" class="form-control" id="dpHelperTextDefault" placeholder="YYYY-MM-DD" aria-describedby="dpHelperTextDefaultHelp" required>
			<button type="button" class="icon" aria-label="Open date picker"></button>
		</div>
	</div>
	<span id="dpHelperTextDefaultHelp" class="help-block">Change this to a short description</span>
</div>

Required/optional fields

We use an asterisk to indicate a field is required.

The convention of using a red asterisk (*) in a label to denote a required field is a long-standing and widely adopted practice in User Experience (UX) and form design.

Example
HTML

Label

Change this to a short description

Label

Change this to a short description

development/documentation/docs/datepicker/examples/required-optional.html

<div class="d-flex flex-wrap gap-24">
	<!-- Required -->
	<div class="form-group required docs-form-state-width">
		<label for="dpRequired">Label</label>
		<div class="datepicker">
			<div class="control">
				<input type="text" class="form-control" id="dpRequired" placeholder="YYYY-MM-DD" aria-describedby="dpRequiredHelp" required>
				<button type="button" class="icon" aria-label="Open date picker"></button>
			</div>
		</div>
		<span id="dpRequiredHelp" class="help-block">Change this to a short description</span>
	</div>

	<!-- Optional -->
	<div class="form-group docs-form-state-width">
		<label for="dpOptional">Label</label>
		<div class="datepicker">
			<div class="control">
				<input type="text" class="form-control" id="dpOptional" placeholder="YYYY-MM-DD" aria-describedby="dpOptionalHelp">
				<button type="button" class="icon" aria-label="Open date picker"></button>
			</div>
		</div>
		<span id="dpOptionalHelp" class="help-block">Change this to a short description</span>
	</div>
</div>

Max width

Dropdown buttons and menus have a max width of 520px.

Example
HTML

development/documentation/docs/datepicker/examples/max-width.html

<div class="docs-form-max-width">
	<label for="dpMaxWidth" class="sr-only">Date picker</label>
	<div class="datepicker">
		<div class="control">
			<input type="text" class="form-control" id="dpMaxWidth" placeholder="YYYY-MM-DD">
			<button type="button" class="icon" aria-label="Open date picker"></button>
		</div>
	</div>
	<span class="docs-sizing-bar" aria-hidden="true"></span>
	<span class="docs-sizing-label" aria-hidden="true">520px</span>
</div>

Accessibility

Keyboard interaction

All buttons should be reachable via Tab and Shift+Tab keys. A visible focus indicator is shown on the focused control.

Example
HTML

Label

Change this to a short description

development/documentation/docs/datepicker/examples/accessibility.html

<div class="form-group required docs-form-state-width">
	<label for="dpAccessibility">Label</label>
	<div class="datepicker">
		<div class="control">
			<input type="text" class="form-control focus" id="dpAccessibility" placeholder="YYYY-MM-DD" aria-describedby="dpAccessibilityHelp" required>
			<button type="button" class="icon" aria-label="Open date picker"></button>
		</div>
	</div>
	<span id="dpAccessibilityHelp" class="help-block">Change this to a short description</span>
</div>

Specs

Date picker specifications with spacing and radius annotations

Developer reference

The following sections describe supported functionality that is not part of the Figma design specification.

Third-party plugin. The interactive date picker examples below are based on the Vue-based Buefy datepicker. Spiris ships CSS only — no JavaScript is bundled. To run these examples, consuming applications load vue.min.js and buefy.min.js alongside the Spiris stylesheet.

Variants

The date picker supports multiple layout and selection variants via Buefy:

Standard date picker with input and dropdown selector
Inline date picker — single selection
Inline date picker — range selection
Date picker with range selection and input
Month and year selection
Fill cell with square borders
Stroke cell with square borders

Info icon

Wrap the <label> and an icon trigger in .label-with-info to place the info icon beside the label with the 8 px gap from the Figma anatomy. On hover or keyboard focus, the tooltip opens upwards (data-bs-placement="top") to reveal the supporting text.

Keep the trigger outside the <label for> so clicking the icon does not focus the input, and mirror the tooltip text into a visually-hidden element that the input references via aria-describedby — that way assistive tech users hear the same help text without depending on the tooltip.

Tooltip behaviour relies on Bootstrap's tooltip plugin (with Popper for positioning). See the Tooltips page for setup details.

Example
HTML

Label

Change this to a short description

development/documentation/docs/datepicker/examples/info-icon.html

<div class="form-group required docs-form-state-width docs-form-group-buefy-datepicker">
	<div class="label-with-info">
		<label for="dpInfoIcon">Label</label>
		<span class="spirisicon spirisicon-sm spirisicon-info" tabindex="0" aria-label="More information about Label" data-bs-toggle="tooltip" data-bs-placement="top" title="Pick the date the entry applies to. Future dates are allowed."></span>
	</div>
	<div id="appInfoIcon">
		<b-datepicker
			id="dpInfoIcon"
			aria-describedby="dpInfoIconHelp dpInfoIconInfo"
			v-model="date"
			editable
			icon="calendar"
			:first-day-of-week="1"
			:nearby-selectable-month-days="true"
			:month-names="month_names"
			:day-names="day_names"
			:show-week-number="true"
			:date-formatter="dateFormatter"
			:date-parser="dateParser"
			placeholder="YYYY-MM-DD">
		</b-datepicker>
	</div>
	<span id="dpInfoIconHelp" class="help-block">Change this to a short description</span>
	<span id="dpInfoIconInfo" class="sr-only">Pick the date the entry applies to. Future dates are allowed.</span>
</div>

With input

An input with a simple dropdown/modal for selecting a date.

Example
HTML

development/documentation/docs/datepicker/examples/inputs-datepicker.html

<div id="app" style="">
	<section>
		<b-field class="form-group docs-form-group-buefy-datepicker" label="Select a date" label-for="datepicker-exemple1">
			<b-datepicker
				id="datepicker-exemple1"
				ref="datepicker"
				v-model="date"
				:years-range="[-100, 100]"
				icon="calendar"
				:first-day-of-week="1"
				:nearby-selectable-month-days=true
				:month-names="month_names"
				:day-names="day_names"
				:show-week-number="showWeekNumber"
				:unselectable-days-of-week="[0, 6]"
				:date-formatter="dateFormatter"
				:date-parser="dateParser"
				editable
				placeholder="YYYY-MM-DD">
				<button class="btn btn-today" @click="date = new Date()">Today</button>
				<button class="btn btn-clear" @click="date = null">Clear</button>
			</b-datepicker>
		</b-field>
	</section>
</div>

Inline date picker — single selection

The date picker can be rendered inline (without an input trigger) for choosing a single date.

Example
HTML

development/documentation/docs/datepicker/examples/inline-datepicker.html

<div id="app2" style="margin: 0 auto; display: block; text-align: center;">
	<b-datepicker
		v-model="date"
		inline
		:years-range="[-100, 100]"
		:focused-date="date"
		:first-day-of-week="1"
		:nearby-selectable-month-days=true
		:month-names="month_names"
		:day-names="day_names"
		:unselectable-days-of-week="[0, 6]"
		:show-week-number="showWeekNumber">
	</b-datepicker>
</div>

Inline date picker — range selection

Inline rendering with range selection — pick a start date and an end date. Dates in between are highlighted.

Example
HTML

development/documentation/docs/datepicker/examples/inline-datepicker-range.html

<div id="app3" style="margin: 0 auto; display: block; text-align: center;">
	<b-datepicker v-model="date"
		inline
		range
		:years-range="[-100, 100]"
		:first-day-of-week="1"
		:nearby-selectable-month-days=true
		:month-names="month_names"
		:day-names="day_names"
		:unselectable-days-of-week="[0, 6]"
		:show-week-number="showWeekNumber">
	</b-datepicker>
</div>

Range selection with input

Select a range of dates from an input trigger. Both start and end dates appear in the input once chosen.

Example
HTML

development/documentation/docs/datepicker/examples/input-datepicker-range.html

<div id="app4">
	<section>
		<b-field class="form-group docs-form-group-buefy-datepicker" label="Select the start date and end date of your vacation:" label-for="datepicker-exemple4">
			<b-datepicker v-model="date"
				ref="datepicker"
				icon="calendar"
				id="datepicker-exemple4"
				range
				editable
				placeholder="YYYY-MM-DD – YYYY-MM-DD"
				:years-range="[-100, 100]"
				:first-day-of-week="1"
				:nearby-selectable-month-days=true
				:month-names="month_names"
				:day-names="day_names"
				:unselectable-days-of-week="[0, 6]"
				:show-week-number="showWeekNumber"
				:date-formatter="dateFormatter"
				:date-parser="dateParser">
			</b-datepicker>
		</b-field>
	</section>
</div>

Month and year selection

A compact picker that lets the user choose a month and a year without selecting a specific day.

Example
HTML

development/documentation/docs/datepicker/examples/month-picker.html

<div id="app5" class="container">
	<b-field label="Select month and year" class="form-group month-picker docs-form-group-buefy-datepicker" label-for="datepicker-exemple5">
		<b-datepicker
			id="datepicker-exemple5"
			type="month"
			editable
			placeholder="YYYY-MM-DD"
			:month-names="month_names"
			:date-formatter="dateFormatter"
			:date-parser="dateParser"
			icon="calendar">
		</b-datepicker>
	</b-field>
</div>

Calendar cell variants

The calendar cell appearance can be customised with modifier classes on the date picker wrapper:

.datepicker-square — fill cell with square borders
.datepicker-stroke.datepicker-square — stroke cell with square borders

Fill cell, square borders

Add .datepicker-square to the date picker wrapper.

Example
HTML

or inline:

development/documentation/docs/datepicker/examples/inputs-datepicker-square.html

<div id="app6">
	<section>
		<b-field class="form-group datepicker-square docs-form-group-buefy-datepicker" label="Select the date:" label-for="datepicker-exemple6">
			<b-datepicker v-model="date"
				ref="datepicker"
				icon="calendar"
				id="datepicker-exemple6"
				type=""
				editable
				placeholder="YYYY-MM-DD"
				:years-range="[-100, 100]"
				:first-day-of-week="1"
				:nearby-selectable-month-days=true
				:month-names="month_names"
				:day-names="day_names"
				:unselectable-days-of-week="[0, 6]"
				:close-on-click="false"
				:show-week-number="showWeekNumber"
				:date-formatter="dateFormatter"
				:date-parser="dateParser">
			</b-datepicker>
		</b-field>
	</section>
</div>
<div class="mb-16">or inline:</div>
<div id="app7">
	<b-datepicker
		class="datepicker-square"
		v-model="date"
		inline
		:years-range="[-100, 100]"
		:focused-date="date"
		:first-day-of-week="1"
		:nearby-selectable-month-days=true
		:month-names="month_names"
		:day-names="day_names"
		:unselectable-days-of-week="[0, 6]"
		:show-week-number="showWeekNumber">
	</b-datepicker>
</div>

Stroke cell, square borders

Add .datepicker-stroke and .datepicker-square to the date picker wrapper.

Example
HTML

development/documentation/docs/datepicker/examples/inputs-datepicker-stroke-square.html

<div id="app9">
	<b-datepicker
		class="datepicker-square datepicker-stroke"
		v-model="date"
		inline
		:years-range="[-100, 100]"
		:focused-date="date"
		:first-day-of-week="1"
		:nearby-selectable-month-days=true
		:month-names="month_names"
		:day-names="day_names"
		:unselectable-days-of-week="[0, 6]"
		:show-week-number="showWeekNumber">
	</b-datepicker>
</div>