REMOVED

This component has been removed from the Framework.

Taxonomic name: M-DATE-RANGE
Extension: FORMS-EXTENDED-A
Added on: v3.0.0 (15/09/17)
Removed on: v5.0.0 (05/10/20)

Date range - native date input variant

Design and usage

For further information about date entry, see the date input page.

Features include:

Minimum and maximum dates able to be specified
Start and end dates of range can be allowed to be the same or set so they are never equal
End date can be automatically set X days, X months or X years ahead; on start date selection

Examples

Standard date

Interactive example

Code example

<fieldset class="m-form-row [ Modifier ]" role="group">
	<legend class="a-label">...</legend>
	<div class="m-form-row__content">
		<ul class="m-date-range" data-module="m-date-range">
			<li class="m-date-range__item m-date-range__item--start">
				<label for="..." class="m-date-range__date">
					<span class="a-label">...</span>
					<input type="date" value="..." id="..." name="..." data-date-title="..." placeholder="..." class="a-date" />
					<span class="m-date-range__ui"></span>
				</label>
			</li>
			<li class="m-date-range__item m-date-range__item--end">
				<label for="..." class="m-date-range__date">
					<span class="a-label">...</span>
					<input type="date" value="..." id="..." name="..." data-date-title="..." placeholder="..." class="a-date" />
					<span class="m-date-range__ui"></span>
				</label>
			</li>
		</ul>
	</div>
</fieldset>

Valid date range

Interactive example

Code example

<fieldset class="m-form-row is-valid [ Modifier ]" role="group">
	<legend class="a-label">...</legend>
	<div class="m-form-row__content">
		<p class="m-form-row__validation-message">...</p>
		<ul class="m-date-range" data-module="m-date-range">
			<li class="m-date-range__item m-date-range__item--start">
				<label for="..." class="m-date-range__date">
					<span class="a-label">...</span>
					<input type="date" value="..." id="..." name="..." data-date-title="..." placeholder="..." class="a-date" />
					<span class="m-date-range__ui"></span>
				</label>
			</li>
			<li class="m-date-range__item m-date-range__item--end">
				<label for="..." class="m-date-range__date">
					<span class="a-label">...</span>
					<input type="date" value="..." id="..." name="..." data-date-title="..." placeholder="..." class="a-date" />
					<span class="m-date-range__ui"></span>
				</label>
			</li>
		</ul>
	</div>
</fieldset>

Errored date range

Interactive example

Code example

<fieldset class="m-form-row is-error [ Modifier ]" role="group" aria-invalid="true">
	<legend class="a-label">...</legend>
	<div class="m-form-row__content">
		<p class="m-form-row__error-message">...</p>
		<ul class="m-date-range" data-module="m-date-range">
			<li class="m-date-range__item m-date-range__item--start">
				<label for="..." class="m-date-range__date">
					<span class="a-label">...</span>
					<input type="date" value="..." id="..." name="..." data-date-title="..." placeholder="..." class="a-date" />
					<span class="m-date-range__ui"></span>
				</label>
			</li>
			<li class="m-date-range__item m-date-range__item--end">
				<label for="..." class="m-date-range__date">
					<span class="a-label">...</span>
					<input type="date" value="..." id="..." name="..." data-date-title="..." placeholder="..." class="a-date" />
					<span class="m-date-range__ui"></span>
				</label>
			</li>
		</ul>
	</div>
</fieldset>

Disabled date range

Interactive example

Code example

<fieldset class="m-form-row is-disabled [ Modifier ]" role="group">
	<legend class="a-label">...</legend>
	<div class="m-form-row__content">
		<ul class="m-date-range" data-module="m-date-range">
			<li class="m-date-range__item m-date-range__item--start">
				<label for="..." class="m-date-range__date">
					<span class="a-label">...</span>
					<input type="date" value="..." id="..." name="..." data-date-title="..." placeholder="..." class="a-date" disabled />
					<span class="m-date-range__ui"></span>
				</label>
			</li>
			<li class="m-date-range__item m-date-range__item--end">
				<label for="..." class="m-date-range__date">
					<span class="a-label">...</span>
					<input type="date" value="..." id="..." name="..." data-date-title="..." placeholder="..." class="a-date" disabled />
					<span class="m-date-range__ui"></span>
				</label>
			</li>
		</ul>
	</div>
</fieldset>

Standard date range

Valid date range

Errored date range

Disabled date range

Development and test

Notes for developers

The input must be of type date this enables the best experience for all users (in particular mobile user) as for modern browsers the user will get the native date control. For older browsers a JavaScript datepicker is enabled.

Note that browser that natively support the date input field will return the date in ISO format so both ISO and the appropriate format for the locale need to be supported within any validation.

When setting the value of the input fields always set it in ISO format (YYYY-MM-DD).

For more information see the MDN web docs on the date input

The input must have the attributes min and max, in the format YYYY-MM-DD, set to limit the date pickers to a date range.

When disabling the date input do not solely rely on the is-disabled class, ensure that the disabled attribute is set on the input field.

If the native form validation needs to be disabled set the novalidate attribute on the form.

Important messages

To help those using assistive technologies, make sure that success/error messages which need to be announced to users have their aria attributes updated to role="alert" and/or aria-live="assertive".

Configuration

When using the date range component settings required can be specified as a global JavaScript object. The variable name can then be passed in using the data attribute data-settings on the m-date-range. The possible settings are covered below:

Attribute	Type	Default	Description
`startValue`	String	`null`	Date must be in the format 'YYYY-MM-DD'
`endValue`	String	`null`	Date must be in the format 'YYYY-MM-DD'
`sameDay`	Boolean	`true`	Set to false if the start and end dates must not be the same
`autosetEndDate`	Boolean	`false`	Set to true if when a start date is selected the end date should automatically be set to X days, X months or X years in the future
`autosetEndDateValue`	Array	`[]`	Must be set if autosetEndDate is set to true. First value in the array must be '`day`', '`month`' or '`year`'. The second value must be the number to increment by eg. `'autosetEndDate': true, 'autosetEndDateValue': [ 'day', 10 ]`
`minDate`	String	`null`	Update the minimum date post load. Date must be in the format 'YYYY-MM-DD'
`maxDate`	String	`null`	Update the maximum date post load. Date must be in the format 'YYYY-MM-DD'

To update the component settings after initial load the function setSettings must be called from the m-date-range with a JavaScript object containing settings in the same format as above.

document.querySelector( '#dateRange' ).dateRange.setSettings(
	{
		autosetEndDate: true,
		autosetEndDateValue: [ 'month', 3 ],
		sameDay: false
	}
);

Changing locale settings

The date format and the accessible text behind the next and previous arrows can be updated for a particular locale.

en: {
	datepicker: {
		locale: 'en-gb',
		previousMonth: 'Previous month',
		nextMonth: 'Next month',
		weekdaysShort: ['S','M','T','W','T','F','S'],
	},
},

For more information on this, see our page on how to change locale settings within JavaScript.

Available date format locales are:
af, ar-ma, ar-sa, ar-tn, ar, az, be, bg, bn, bo, br, bs, ca, cs, cv, cy, da, de-at, de, dv, el, en-au, en-ca, en-gb, en-ie, en-nz, eo, es-do, es, et, eu, fa, fi, fo, fr-ca, fr-ch, fr, fy, gd, dl, he, hi, hr, hu, hy-am, id, id, it, ja, jv, ka, kk, km, ko, ky, lb, lo, lt, lv, me, mk, ml, mr, ms-my, ms, my, nb, ne, nl, nn, pa-in, pl, pt-br, pt, ro, ru, se, si, sk, sl, sq, sr-cyrl, sr, ss, sv, sw, ta, te, th, tl-ph, tlh, tr, tzl, tzm-latn, tzm, uk, uz, vi, x-pseudo, zh-cn, zh-tw

Extension component

This component forms part of the 'forms-extended-a' extension and so requires an additional stylesheet to be loaded in order to be used; include the following code in the header of your page to attach the relevant additional stylesheet:

<!--[if !IE | gt IE 8]><!-->
	<link media="all" href="[ CDN Folder Path ]/css/customer/forms-extended-a.css" rel="stylesheet" />
<!--<![endif]-->
<!--[if lte IE 8]>
	<link media="all" href="[ CDN Folder Path ]/css/customer/forms-extended-a-unmq.css" rel="stylesheet" />
<![endif]-->

Notes for testers

In IE11 the date icon will look fuzzy; this is a rendering issue with the browser when a background is on an element that has rounded corners.
Depending on the browser's support of the date field, it may not limit the user to entering the date in a particular format; this is perfectly acceptable but the form must have validation in place to catch any errors with the dates entered and present an error message back to the user. This message does not have to be shown real-time, but can appear once the user has attempted to submit the form.
Ensure that the field has a correctly associated label; this not only provides context to the field for assistive technology users, but also a larger clickable area to select the field. Clicking / pressing on the label should cause the date field to gain focus.
Users should be able to copy and paste if necessary.
Highlight today's date and the selected date with clear variation between them
Users should be able to easily identify and distinguish between selectable and non-selectable dates, today's date, the selected date and weekends.
The calendar should have a clear hover state to help users identify the correct date.
For some applications, past dates may need to be disabled.
Clickable / tappable area of each day should be an appropriate size.

Classes overview

The following table gives you a quick overview of the CSS classes that can be applied.

Class	Outcome	Required	Applied to
`.m-date-range`	Base style for a date range	Yes	`.m-form-row__content > ul`
`.m-date-range__item`	Base style for a date range input wrapper	Yes	`.m-date-range > li`
`.m-date-range__item--start`	Modifier for the start date wrapper	Yes	`.m-date-range > li:first-child`
`.m-date-range__item--end`	Modifier for the end date wrapper	Yes	`.m-date-range > li:last-child`
`.m-date-range__ui`	Styling for UI elements required for the date range input	Yes	`.m-date-range__item > span:last-child`

Component releases

Added on: v3.0.0 (15/09/17)
Removed on: v5.0.0 (05/10/20)

Latest update:

Full version history

A full history of changes and enhancements detailing all minor and major updates to the component.

View full version history

Want something new in Framework, or to chat about an issue you're having with it?

Contact the team