components

DatePicker (code)

Allows users to enter a date. This can be done by either having the fill out the date via an input, but also provides the user with a calendar view for easier date selection.

code

design

Pick your date

import { DatePicker } from '@mediahuis/chameleon-react'

() => {
  const [date, setDate] = React.useState(new Date());

  return (
    <DatePicker
      id="top"
      label="Pick your date"
      onChange={date => setDate(date)}
      value={date}
    />
  );
};

() => {
  const [date, setDate] = React.useState(new Date());
  return (
    <DatePicker
      id="top"
      label="Pick your date"
      onChange={date => setDate(date)}
      value={date}
    />
  );
};

Props

OnChange

default: undefined

DatePicker's onChange function is slightly different than that from TextField. Instead of returning the input field's value, we return 2 arguments.

The first argument is the JavaScript Date object of the currently selected date. However, this value can be false in two cases: if a user manually inputs a date that is either not yet complete (e.g. 02/04/202_) or inputs an invalid date (e.g. 30/02/2020).
The second argument is an object that contains more information about the selected date. The current properties of this object are:
- disabled: This will be true if the currently selected date is inside your range of disabledDays (see below).
- formattedDate: This is a string representation of the currently selected date, formatted by the format prop.

Pick your date

import { DatePicker } from '@mediahuis/chameleon-react'

() => {
  const [date, setDate] = React.useState(new Date());

  return (
    <DatePicker
      id="onchange"
      label="Pick your date"
      onChange={(date, properties) => {
        alert(`
          JavaScript date: ${date}
          Disabled: ${properties.disabled}
          FormattedDate: ${properties.formattedDate}
        `);
        setDate(date);
      }}
      value={date}
    />
  );
};

() => {
  const [date, setDate] = React.useState(new Date());
  return (
    <DatePicker
      id="onchange"
      label="Pick your date"
      onChange={(date, properties) => {
        alert(`
          JavaScript date: ${date}
          Disabled: ${properties.disabled}
          FormattedDate: ${properties.formattedDate}
        `);
        setDate(date);
      }}
      value={date}
    />
  );
};

DisabledDays

default: undefined

To prevent a user from selecting certain dates, you can supply the disabledDays prop. This prop can be either:

A Date object. This will disable the specific day.
A range object with from and to keys to match a range of days.
An object with a before and/or after key to match the days before and/or after the given date.
An object with a daysOfWeek array to match specific days of week.
A function taking the day as first argument and returning a boolean value.
An array of the above.

Date object

This example disables a single day.

Pick your date

import { DatePicker } from '@mediahuis/chameleon-react'

() => {
  const [date, setDate] = React.useState(new Date(2020, 3, 19));

  return (
    <DatePicker
      id="dateobject"
      label="Pick your date"
      onChange={setDate}
      value={date}
      disabledDays={new Date(2020, 3, 20)}
    />
  );
};

() => {
  const [date, setDate] = React.useState(new Date(2020, 3, 19));
  return (
    <DatePicker
      id="dateobject"
      label="Pick your date"
      onChange={setDate}
      value={date}
      disabledDays={new Date(2020, 3, 20)}
    />
  );
};

Range object

In this example, a range, described by from and to keys, is disabled.

Pick your date

import { DatePicker } from '@mediahuis/chameleon-react'

() => {
  const [date, setDate] = React.useState(new Date(2020, 2, 14));

  return (
    <DatePicker
      id="range"
      label="Pick your date"
      onChange={setDate}
      value={date}
      disabledDays={{ from: new Date(2020, 2, 21), to: new Date(2020, 2, 30) }}
    />
  );
};

() => {
  const [date, setDate] = React.useState(new Date(2020, 2, 14));
  return (
    <DatePicker
      id="range"
      label="Pick your date"
      onChange={setDate}
      value={date}
      disabledDays={{ from: new Date(2020, 2, 21), to: new Date(2020, 2, 30) }}
    />
  );
};

Before

When providing an object with a before key, all dates before that date (not including the date itself) are disabled.

Pick your date

import { DatePicker } from '@mediahuis/chameleon-react'

() => {
  const [date, setDate] = React.useState(new Date(2020, 2, 28));

  return (
    <DatePicker
      id="before"
      label="Pick your date"
      onChange={setDate}
      value={date}
      disabledDays={{ before: new Date(2020, 2, 21) }}
    />
  );
};

() => {
  const [date, setDate] = React.useState(new Date(2020, 2, 28));
  return (
    <DatePicker
      id="before"
      label="Pick your date"
      onChange={setDate}
      value={date}
      disabledDays={{ before: new Date(2020, 2, 21) }}
    />
  );
};

After

When providing an object with an after key, all dates after that date (not including the date itself) are disabled.

Pick your date

import { DatePicker } from '@mediahuis/chameleon-react'

() => {
  const [date, setDate] = React.useState(new Date(2020, 2, 28));

  return (
    <DatePicker
      id="after"
      label="Pick your date"
      onChange={setDate}
      value={date}
      disabledDays={{ after: new Date(2020, 2, 29) }}
    />
  );
};

() => {
  const [date, setDate] = React.useState(new Date(2020, 2, 28));
  return (
    <DatePicker
      id="after"
      label="Pick your date"
      onChange={setDate}
      value={date}
      disabledDays={{ after: new Date(2020, 2, 29) }}
    />
  );
};

Before and after

The before and after keys can be combined to create a range of "allowedDates". The next example will only allow a single week.

Pick your date

import { DatePicker } from '@mediahuis/chameleon-react'

() => {
  const [date, setDate] = React.useState(new Date(2020, 2, 28));

  return (
    <DatePicker
      id="beforeandafter"
      label="Pick your date"
      onChange={setDate}
      value={date}
      disabledDays={{
        before: new Date(2020, 2, 23),
        after: new Date(2020, 2, 29),
      }}
    />
  );
};

() => {
  const [date, setDate] = React.useState(new Date(2020, 2, 28));
  return (
    <DatePicker
      id="beforeandafter"
      label="Pick your date"
      onChange={setDate}
      value={date}
      disabledDays={{
        before: new Date(2020, 2, 23),
        after: new Date(2020, 2, 29),
      }}
    />
  );
};

Days of week

An array of numbers corresponding to days to be disabled (Note: starting on Sunday and zero-index, so Sunday is 0). The example below disabled every Friday and every Sunday.

Pick your date

import { DatePicker } from '@mediahuis/chameleon-react'

() => {
  const [date, setDate] = React.useState(new Date(2020, 2, 28));

  return (
    <DatePicker
      id="daysofweek"
      label="Pick your date"
      onChange={setDate}
      value={date}
      inline
      disabledDays={{
        daysOfWeek: [0, 5],
      }}
    />
  );
};

() => {
  const [date, setDate] = React.useState(new Date(2020, 2, 28));
  return (
    <DatePicker
      id="daysofweek"
      label="Pick your date"
      onChange={setDate}
      value={date}
      inline
      disabledDays={{
        daysOfWeek: [0, 5],
      }}
    />
  );
};

Function

The function takes the day as the first argument. If the function returns true, the day is disabled. The example below disables every day that is not even.

Pick your date

import { DatePicker } from '@mediahuis/chameleon-react'

() => {
  const [date, setDate] = React.useState(new Date(2020, 2, 28));

  return (
    <DatePicker
      id="function"
      label="Pick your date"
      onChange={setDate}
      value={date}
      disabledDays={day => {
        return day.getDate() % 2;
      }}
    />
  );
};

() => {
  const [date, setDate] = React.useState(new Date(2020, 2, 28));
  return (
    <DatePicker
      id="function"
      label="Pick your date"
      onChange={setDate}
      value={date}
      disabledDays={day => {
        return day.getDate() % 2;
      }}
    />
  );
};

Array

An array can be used to combine any number of the above options. The example below disables all days except a single week, and in that week, Wednesday, Saturday and Sunday are disabled.

Pick your date

import { DatePicker } from '@mediahuis/chameleon-react'

() => {
  const [date, setDate] = React.useState(new Date(2020, 2, 26));

  return (
    <DatePicker
      id="array"
      label="Pick your date"
      onChange={setDate}
      value={date}
      disabledDays={[
        {
          before: new Date(2020, 2, 23),
          after: new Date(2020, 2, 29),
        },
        { daysOfWeek: [0, 6, 3] },
      ]}
    />
  );
};

() => {
  const [date, setDate] = React.useState(new Date(2020, 2, 26));
  return (
    <DatePicker
      id="array"
      label="Pick your date"
      onChange={setDate}
      value={date}
      disabledDays={[
        {
          before: new Date(2020, 2, 23),
          after: new Date(2020, 2, 29),
        },
        { daysOfWeek: [0, 6, 3] },
      ]}
    />
  );
};

Mask & format

mask default: 99/99/99

format default: DD/MM/YYY

To visually aid the user with the expected format, you can use an input mask. Input masks will display a template of the expected value. The mask is built out of several definitions:

9: numeric
a: alphabetical
*: alphanumeric

Linked to the input mask, is the format of the date. The available tokens for parsing date are:

YY Two-digit year (e.g. 18)
YYYY Four-digit year (e.g. 2018)
M Month, beginning at 1 (e.g. 1-12)
MM Month, 2-digits (e.g. 01-12)
MMM The abbreviated month name (e.g. Jan-Dec)
MMMM The full month name (e.g. January-December)
D Day of month (e.g. 1-31)
DD Day of month, 2-digits (e.g. 01-31)
H Hours (e.g. 0-23)
HH Hours, 2-digits (e.g. 00-23)
h Hours, 12-hour clock (e.g. 1-12)
hh Hours, 12-hour clock, 2-digits (e.g. 01-12)
m Minutes (e.g. 0-59)
mm Minutes, 2-digits (e.g. 00-59)
s Seconds (e.g. 0-59)
ss Seconds, 2-digits (e.g. 00-59)
S Hundreds of milliseconds, 1-digit (e.g. 0-9)
SS Tens of milliseconds, 2-digits (e.g. 00-99)
SSS Milliseconds, 3-digits (e.g. 000-999)
Z Offset from UTC (e.g. -05:00)
ZZ Compact offset from UTC, 2-digits (e.g. -0500)
A Post or ante meridiem, upper-case (e.g. AM PM)
a Post or ante meridiem, lower-case (e.g. am pm)
Do Day of Month with ordinal (e.g. 1st... 31st)

Note: It is important that if you change one of these values, that the other value is still compliant. Setting a mask of 99-aaa won't make much sense if your format is still on default DD/MM/YYYY.

Pick your date

import { DatePicker } from '@mediahuis/chameleon-react'

() => {
  const [date, setDate] = React.useState(new Date(2020, 2, 26));

  return (
    <DatePicker
      id="mask"
      label="Pick your date"
      mask="99-aaa"
      format="DD-MMM"
      onChange={setDate}
      value={date}
    />
  );
};

() => {
  const [date, setDate] = React.useState(new Date(2020, 2, 26));
  return (
    <DatePicker
      id="mask"
      label="Pick your date"
      mask="99-aaa"
      format="DD-MMM"
      onChange={setDate}
      value={date}
    />
  );
};

Localization

DatePicker has localization built in. This built-in localization may be different between brands, but this is logic that is provided by Chameleon so that you as a developer don't have to worry about it.

In the example below, you can see the localization by properties such as the first day of the week, the short names of the days, ...

Pick your date

import { DatePicker } from '@mediahuis/chameleon-react'

() => {
  const [date, setDate] = React.useState(new Date(2020, 2, 26));

  return (
    <>
      <DatePicker
        id="localization"
        label="Pick your date"
        onChange={setDate}
        value={date}
      />
    </>
  );
};

() => {
  const [date, setDate] = React.useState(new Date(2020, 2, 26));
  return (
    <>
      <DatePicker
        id="localization"
        label="Pick your date"
        onChange={setDate}
        value={date}
      />
    </>
  );
};

Error

default: false

To convey an error to the user, you can set the error prop to true. This can come in handy to indicate an invalid date, or if the user would type in a date that would be outside of your date range.

In the example below, try removing a character or set the date to an impossible date (e.g. 30/02/2020).

Pick your date

When were you born?

import { DatePicker } from '@mediahuis/chameleon-react'

() => {
  const [date, setDate] = React.useState(new Date(2020, 2, 26));

  return (
    <>
      <DatePicker
        id="error"
        label="Pick your date"
        onChange={setDate}
        value={date}
        error={date === false}
        message={date ? 'When were you born?' : 'Invalid date selected!'}
      />
    </>
  );
};

() => {
  const [date, setDate] = React.useState(new Date(2020, 2, 26));
  return (
    <>
      <DatePicker
        id="error"
        label="Pick your date"
        onChange={setDate}
        value={date}
        error={date === false}
        message={date ? 'When were you born?' : 'Invalid date selected!'}
      />
    </>
  );
};

Inline

default: false

By default, the calendar will be closed and only opens when clicking the calender icon. You can have the calendar open by default and act as an inline element by passing in the inline prop.

Pick your date

import { DatePicker } from '@mediahuis/chameleon-react'

() => {
  const [date, setDate] = React.useState(new Date(2020, 2, 26));

  return (
    <>
      <DatePicker
        id="inline"
        label="Pick your date"
        inline
        onChange={setDate}
        value={date}
      />
    </>
  );
};

() => {
  const [date, setDate] = React.useState(new Date(2020, 2, 26));
  return (
    <>
      <DatePicker
        id="inline"
        label="Pick your date"
        inline
        onChange={setDate}
        value={date}
      />
    </>
  );
};

Disabled

default: false

Marking a DatePicker as disabled, will disable all interaction with the element.

Do not pick your date

import { DatePicker } from '@mediahuis/chameleon-react'

() => {
  const [date, setDate] = React.useState(new Date(2020, 2, 26));

  return (
    <DatePicker
      id="disabled"
      label="Do not pick your date"
      disabled
      onChange={setDate}
      value={date}
    />
  );
};

() => {
  const [date, setDate] = React.useState(new Date(2020, 2, 26));
  return (
    <DatePicker
      id="disabled"
      label="Do not pick your date"
      disabled
      onChange={setDate}
      value={date}
    />
  );
};

OptionalLabel (Required fields)

default: undefined

By default the DatePicker is always required. To make a DatePicker optional you can add the optionalLabel prop.

With Chameleon we take a specific approach where we encourage marking optional fields, not required. The majority of fields in a form are always required. Indicating that fields are required make users more fearful, it increases the risk of errors and reduces the form completion rate.

Pick your date(Optional)

import { DatePicker } from '@mediahuis/chameleon-react'

() => {
  const [date, setDate] = React.useState(new Date(2020, 2, 26));

  return (
    <DatePicker
      id="label"
      label="Pick your date"
      optionalLabel="Optional"
      onChange={setDate}
      value={date}
    />
  );
};

() => {
  const [date, setDate] = React.useState(new Date(2020, 2, 26));
  return (
    <DatePicker
      id="label"
      label="Pick your date"
      optionalLabel="Optional"
      onChange={setDate}
      value={date}
    />
  );
};

PickerInputOnly

default: false

If you still want full functionality of the DatePicker, but don't want users to be able to manually enter a date, you can pass in the pickerInputOnly prop.

Pick your date

import { DatePicker } from '@mediahuis/chameleon-react'

() => {
  const [date, setDate] = React.useState(new Date(2020, 2, 26));

  return (
    <DatePicker
      id="disabled"
      label="Pick your date"
      pickerInputOnly
      onChange={setDate}
      value={date}
    />
  );
};

() => {
  const [date, setDate] = React.useState(new Date(2020, 2, 26));
  return (
    <DatePicker
      id="disabled"
      label="Pick your date"
      pickerInputOnly
      onChange={setDate}
      value={date}
    />
  );
};

Label Props

As with other input elements, DatePicker also has a wide range of extra properties to convey even more meaning.

Pick your date(Not needed)What dates are valid?

Go Charlie, it's your birthday

import { DatePicker } from '@mediahuis/chameleon-react'

() => {
  const [date, setDate] = React.useState(new Date(2020, 2, 26));

  return (
    <DatePicker
      id="label"
      label="Pick your date"
      action={<LinkText>What dates are valid?</LinkText>}
      message="Go Charlie, it's your birthday"
      optionalLabel="Not needed"
      onChange={setDate}
      value={date}
    />
  );
};

() => {
  const [date, setDate] = React.useState(new Date(2020, 2, 26));
  return (
    <DatePicker
      id="label"
      label="Pick your date"
      action={<LinkText>What dates are valid?</LinkText>}
      message="Go Charlie, it's your birthday"
      optionalLabel="Not needed"
      onChange={setDate}
      value={date}
    />
  );
};