Datepicker

Import

import { Datepicker } from '@contentful/f36-components';
// or
import { Datepicker } from '@contentful/f36-datepicker';

Examples

Basic

Display Datepicker component with text input

Hide code
function BasicExample() {
  const [selectedDay, setSelectedDay] = useState(new Date());

  return <Datepicker selected={selectedDay} onSelect={setSelectedDay} />;
}
function BasicExample() {
  const [selectedDay, setSelectedDay] = useState(new Date());

  return <Datepicker selected={selectedDay} onSelect={setSelectedDay} />;
}
Open in Playground

Date Formats

Datepicker supports printing out different formats to users, see https://date-fns.org/v2.16.1/docs/format

At Contentful we use dd LLL yyyy format to communicate date to users, example 31 Jan 2021

Hide code
function FormatExample() {
  const [selectedDay, setSelectedDay] = useState(new Date());

  return (
    <Flex marginBottom="spacingM" flexDirection="column" fullWidth>
      <Box marginBottom="spacingM">
        <Datepicker
          dateFormat="do LLL yyyy"
          selected={selectedDay}
          onSelect={setSelectedDay}
        />
      </Box>
      <Box>
        <Datepicker
          dateFormat="dd.MM.yyyy"
          selected={selectedDay}
          onSelect={setSelectedDay}
        />
      </Box>
    </Flex>
  );
}
function FormatExample() {
  const [selectedDay, setSelectedDay] = useState(new Date());

  return (
    <Flex marginBottom="spacingM" flexDirection="column" fullWidth>
      <Box marginBottom="spacingM">
        <Datepicker
          dateFormat="do LLL yyyy"
          selected={selectedDay}
          onSelect={setSelectedDay}
        />
      </Box>
      <Box>
        <Datepicker
          dateFormat="dd.MM.yyyy"
          selected={selectedDay}
          onSelect={setSelectedDay}
        />
      </Box>
    </Flex>
  );
}
Open in Playground

Visual States

Visual states indicates to users certain messages through UI.

Communicate to the users in text why the Datepicker is in a specific state, example:

Disabled: "You don't have access to edit this field!" Invalid: "Please enter a valid date!"

Hide code
function VisualStatesExample() {
  const [selectedDay, setSelectedDay] = useState(new Date());

  return (
    <>
      <SectionHeading>Disabled</SectionHeading>
      <Datepicker
        selected={selectedDay}
        onSelect={setSelectedDay}
        inputProps={{ isDisabled: true }}
      />
      <br />
      <SectionHeading>Invalid</SectionHeading>
      <Datepicker
        selected={selectedDay}
        onSelect={setSelectedDay}
        inputProps={{ isInvalid: true }}
      />
    </>
  );
}
function VisualStatesExample() {
  const [selectedDay, setSelectedDay] = useState(new Date());

  return (
    <>
      <SectionHeading>Disabled</SectionHeading>
      <Datepicker
        selected={selectedDay}
        onSelect={setSelectedDay}
        inputProps={{ isDisabled: true }}
      />
      <br />
      <SectionHeading>Invalid</SectionHeading>
      <Datepicker
        selected={selectedDay}
        onSelect={setSelectedDay}
        inputProps={{ isInvalid: true }}
      />
    </>
  );
}
Open in Playground

Wrapped in FormControl

You can use Datepicker with the FormControl in order to enhance layout with input label, help text or validation message.

Hide code
function WithFormControlExample() {
  const [selectedDay, setSelectedDay] = useState(new Date());

  return (
    <FormControl id="date" isRequired>
      <FormControl.Label>Date</FormControl.Label>
      <Datepicker selected={selectedDay} onSelect={setSelectedDay} />
      <FormControl.HelpText>Please enter a publish date</FormControl.HelpText>
    </FormControl>
  );
}
function WithFormControlExample() {
  const [selectedDay, setSelectedDay] = useState(new Date());

  return (
    <FormControl id="date" isRequired>
      <FormControl.Label>Date</FormControl.Label>
      <Datepicker selected={selectedDay} onSelect={setSelectedDay} />
      <FormControl.HelpText>Please enter a publish date</FormControl.HelpText>
    </FormControl>
  );
}
Open in Playground

Limiting the date range

Set mininum and/or maximum dates to limit users to choose from a specific period in time.

Use the fromDate and toDate properties to control time frames.

Hide code
function LimitingTheDateRangeExample() {
  const [selectedDay, setSelectedDay] = useState(new Date());
  const fromDate = new Date();
  const twoYearsFromNow = new Date(
    new Date(fromDate).setFullYear(fromDate.getFullYear() + 2),
  );

  return (
    <Datepicker
      fromDate={fromDate}
      toDate={twoYearsFromNow}
      selected={selectedDay}
      onSelect={setSelectedDay}
    />
  );
}
function LimitingTheDateRangeExample() {
  const [selectedDay, setSelectedDay] = useState(new Date());
  const fromDate = new Date();
  const twoYearsFromNow = new Date(
    new Date(fromDate).setFullYear(fromDate.getFullYear() + 2),
  );

  return (
    <Datepicker
      fromDate={fromDate}
      toDate={twoYearsFromNow}
      selected={selectedDay}
      onSelect={setSelectedDay}
    />
  );
}
Open in Playground

Multiple months

If you need to show more than a month at once, use the numberOfMonths property.

Hide code
function WithMultipleMonthsExample() {
  const [selectedDay, setSelectedDay] = useState(new Date());

  return (
    <Datepicker
      selected={selectedDay}
      onSelect={setSelectedDay}
      numberOfMonths={2}
    />
  );
}
function WithMultipleMonthsExample() {
  const [selectedDay, setSelectedDay] = useState(new Date());

  return (
    <Datepicker
      selected={selectedDay}
      onSelect={setSelectedDay}
      numberOfMonths={2}
    />
  );
}
Open in Playground

Open by default

Use the defaultIsOpen property to open the dropdown and display the Calendar by default without user interaction.

Note: the Calendar closes by pressing the escape key or by clicking outside of the Datepicker.

Hide code
function DefaultOpenExample() {
  const [selectedDay, setSelectedDay] = useState(new Date());

  return (
    <Datepicker
      defaultIsOpen
      selected={selectedDay}
      onSelect={setSelectedDay}
    />
  );
}
function DefaultOpenExample() {
  const [selectedDay, setSelectedDay] = useState(new Date());

  return (
    <Datepicker
      defaultIsOpen
      selected={selectedDay}
      onSelect={setSelectedDay}
    />
  );
}
Open in Playground

Custom

If you need a custom solution, you can build it by leveraging our lower-level components, such as Calendar, Popover, and TextInput. For example, Datepicker that uses text input as a trigger without a button.

Hide code
function CustomExample() {
  const DATE_FORMAT = 'yyyy-MM-dd'; // e.g. 2022-01-31

  const [selected, setSelected] = useState(new Date('2022-04-15'));
  const [isPopoverOpen, setIsPopoverOpen] = useState(false);
  const [inputValue, setInputValue] = useState(() =>
    selected ? format(selected, DATE_FORMAT) : '',
  );
  const [isInputInvalid, setIsInputInvalid] = useState(false);
  const popoverWasClosed = useRef(false);

  const closePopover = () => {
    popoverWasClosed.current = true;
    setIsPopoverOpen(false);
  };

  const handleDaySelect = (date) => {
    if (date) {
      setSelected(date);
      setInputValue(format(date, DATE_FORMAT));
      closePopover();
    }
  };

  const handleInputFocus = () => {
    // when popover gets closed focus returns to the input,
    // we want to prevent popover to be opened in this case
    if (popoverWasClosed.current) {
      popoverWasClosed.current = false;
      return;
    }

    setIsPopoverOpen((state) => !state);
  };

  const hendleInputKeyDown = (event) => {
    if (event.key === 'Enter' && !isInputInvalid) {
      event.preventDefault();
      setIsPopoverOpen(true);
    }
  };

  const handleInputChange = (e) => {
    const value = e.currentTarget.value;
    setInputValue(value);

    const date = parse(value, DATE_FORMAT, new Date());
    if (isValid(date)) {
      setIsInputInvalid(false);
      setSelected(date);
    } else {
      setIsInputInvalid(true);
      setSelected(undefined);
    }
  };

  return (
    <Popover isOpen={isPopoverOpen} onClose={closePopover}>
      <Popover.Trigger>
        <TextInput
          placeholder={format(new Date(), DATE_FORMAT)}
          value={inputValue}
          onChange={handleInputChange}
          onFocus={handleInputFocus}
          onKeyDown={hendleInputKeyDown}
          isInvalid={isInputInvalid}
          aria-label="Choose date"
        />
      </Popover.Trigger>
      <Popover.Content>
        <FocusLock returnFocus={true}>
          <Calendar
            className={css({
              padding: tokens.spacingM,
            })}
            mode="single"
            selected={selected}
            onSelect={handleDaySelect}
            initialFocus={false}
            defaultMonth={selected}
          />
        </FocusLock>
      </Popover.Content>
    </Popover>
  );
}
function CustomExample() {
  const DATE_FORMAT = 'yyyy-MM-dd'; // e.g. 2022-01-31

  const [selected, setSelected] = useState(new Date('2022-04-15'));
  const [isPopoverOpen, setIsPopoverOpen] = useState(false);
  const [inputValue, setInputValue] = useState(() =>
    selected ? format(selected, DATE_FORMAT) : '',
  );
  const [isInputInvalid, setIsInputInvalid] = useState(false);
  const popoverWasClosed = useRef(false);

  const closePopover = () => {
    popoverWasClosed.current = true;
    setIsPopoverOpen(false);
  };

  const handleDaySelect = (date) => {
    if (date) {
      setSelected(date);
      setInputValue(format(date, DATE_FORMAT));
      closePopover();
    }
  };

  const handleInputFocus = () => {
    // when popover gets closed focus returns to the input,
    // we want to prevent popover to be opened in this case
    if (popoverWasClosed.current) {
      popoverWasClosed.current = false;
      return;
    }

    setIsPopoverOpen((state) => !state);
  };

  const hendleInputKeyDown = (event) => {
    if (event.key === 'Enter' && !isInputInvalid) {
      event.preventDefault();
      setIsPopoverOpen(true);
    }
  };

  const handleInputChange = (e) => {
    const value = e.currentTarget.value;
    setInputValue(value);

    const date = parse(value, DATE_FORMAT, new Date());
    if (isValid(date)) {
      setIsInputInvalid(false);
      setSelected(date);
    } else {
      setIsInputInvalid(true);
      setSelected(undefined);
    }
  };

  return (
    <Popover isOpen={isPopoverOpen} onClose={closePopover}>
      <Popover.Trigger>
        <TextInput
          placeholder={format(new Date(), DATE_FORMAT)}
          value={inputValue}
          onChange={handleInputChange}
          onFocus={handleInputFocus}
          onKeyDown={hendleInputKeyDown}
          isInvalid={isInputInvalid}
          aria-label="Choose date"
        />
      </Popover.Trigger>
      <Popover.Content>
        <FocusLock returnFocus={true}>
          <Calendar
            className={css({
              padding: tokens.spacingM,
            })}
            mode="single"
            selected={selected}
            onSelect={handleDaySelect}
            initialFocus={false}
            defaultMonth={selected}
          />
        </FocusLock>
      </Popover.Content>
    </Popover>
  );
}
Open in Playground

Accessibility

• Keyboard navigation is supported
• Necessary aria roles are provided by default
• When providing a label, ensure it's linked to the text input