Date Picker API - React Magma

Use the date input when you want the user to input a date in the format you choose.

Basic Usage

Date

April 2025

S	M	T	W	T	F	S

import React from 'react';

import { DatePicker } from 'react-magma-dom';

export function Example() {
  return <DatePicker labelText="Date" />;
}

Default Date

By default, no date value is selected. You can add a default date, by using the defaultDate prop.

Date

January 2025

S	M	T	W	T	F	S

import React from 'react';

import { DatePicker } from 'react-magma-dom';

export function Example() {
  return <DatePicker defaultDate={new Date(2025, 1, 0)} labelText="Date" />;
}

Value

The value prop can also be used so set the date value externally. It will override the defaultDate if both are passed.

Date

January 2000

S	M	T	W	T	F	S

import React from 'react';

import { DatePicker } from 'react-magma-dom';

export function Example() {
  return (
    <DatePicker
      defaultDate={new Date(2025, 1, 0)}
      labelText="Date"
      value={new Date(2000, 1, 0)}
    />
  );
}

Minimum and Maximum Dates

Minimum and Maximum dates can be passed in as props to disallow the selection of a date outside of a specific range. If a date value is passed in that does not fit in to the range given, the date picker will try to give focus when entering the calendar on today's date, then the minimum date, and finally the maximum date.

Date

February 2025

S	M	T	W	T	F	S

import React from 'react';

import { DatePicker, getDateFromString, inDateRange } from 'react-magma-dom';

export function Example() {
  const [chosenDate, setChosenDate] = React.useState<Date | undefined>(
    undefined
  );
  const minDate = new Date(2025, 1, 2);
  const maxDate = new Date(2025, 1, 20);

  function handleDateChange(newChosenDate: Date) {
    setChosenDate(newChosenDate);
  }

  function hasErrorMessage() {
    const convertedMinDate = getDateFromString(minDate);
    const convertedMaxDate = getDateFromString(maxDate);

    if (
      chosenDate &&
      !inDateRange(chosenDate, convertedMinDate, convertedMaxDate)
    ) {
      return `Please enter a date within the range ${minDate} - ${maxDate}`;
    }

    return;
  }

  return (
    <DatePicker
      labelText="Date"
      minDate={minDate}
      maxDate={maxDate}
      onDateChange={handleDateChange}
      errorMessage={hasErrorMessage()}
    />
  );
}

Clearing the Date

Dates can be cleared with the isClearable prop, or programmatically through the onDateChange function by passing null.

Chosen Date:

Date

April 2025

S	M	T	W	T	F	S

import React from 'react';

import { DatePicker, Button } from 'react-magma-dom';

export function Example() {
  const [chosenDate, setChosenDate] = React.useState<Date | undefined>(
    undefined
  );

  function handleDateChange(newChosenDate: Date | null) {
    setChosenDate(newChosenDate);
  }

  return (
    <div>
      <p>
        <strong>Chosen Date: </strong>
        {chosenDate && (
          <span>
            {`${
              chosenDate.getMonth() + 1
            }/${chosenDate.getDate()}/${chosenDate.getFullYear()}`}
          </span>
        )}
      </p>
      <DatePicker
        labelText="Date"
        value={chosenDate}
        onDateChange={handleDateChange}
        isClearable
      />
      <br />
      <Button onClick={() => handleDateChange(null)}>Clear Date</Button>
    </div>
  );
}

Placeholder Text

By default, the placeholder text of the input is 'mm/dd/yyyy'. You can override this by using the placeholder prop. Note: the expected date format should appear somewhere in either the labelText or the placeholder.

Birthday

April 2025

S	M	T	W	T	F	S

import React from 'react';

import { DatePicker } from 'react-magma-dom';

export function Example() {
  return (
    <DatePicker
      placeholder="Your birthday (format mm/dd/yyyy)"
      labelText="Birthday"
    />
  );
}

Helper Message

Help me

This is your help

April 2025

S	M	T	W	T	F	S

import React from 'react';

import { DatePicker } from 'react-magma-dom';

export function Example() {
  return <DatePicker labelText="Help me" helperMessage="This is your help" />;
}

Error Message

Error *

You made an error

April 2025

S	M	T	W	T	F	S

import React from 'react';

import { DatePicker } from 'react-magma-dom';

export function Example() {
  return (
    <DatePicker labelText="Error *" errorMessage="You made an error" required />
  );
}

Inverse

Date

April 2025

S	M	T	W	T	F	S

import React from 'react';

import { DatePicker, Card, CardBody } from 'react-magma-dom';

export function Example() {
  return (
    <Card isInverse>
      <CardBody>
        <DatePicker labelText="Date" isInverse />
      </CardBody>
    </Card>
  );
}

Date Formats

By default, the component uses the MM/dd/yyyy date format. This can be changed in the I18nContext. In addition to the default, the component supports the following formats: dd/MM/yyyy, yyyy/MM/dd, yyyy/dd/MM and MMMM d, yyyy.

Date format: dd/MM/yyyy

April 2025

S	M	T	W	T	F	S

import React from 'react';

import { DatePicker, I18nContext, defaultI18n } from 'react-magma-dom';

export function Example() {
  return (
    <I18nContext.Provider
      value={{
        ...defaultI18n,
        dateFormat: 'dd/MM/yyyy',
      }}
    >
      <DatePicker labelText="Date format: dd/MM/yyyy" />
    </I18nContext.Provider>
  );
}

Events

On Input Change

The onInputChange is passed to the input's onChange method that is in the DatePicker component.

Input Value:

Date

April 2025

S	M	T	W	T	F	S

import React from 'react';

import { DatePicker } from 'react-magma-dom';

export function Example() {
  const [inputValue, setInputValue] = React.useState<string>('');

  function handleInputChange(event: React.EventChangeHandler) {
    setInputValue(event.target.value);
  }

  return (
    <div>
      <p>
        <strong>Input Value: </strong>
        {inputValue}
      </p>
      <DatePicker labelText="Date" onInputChange={handleInputChange} />
    </div>
  );
}

On Date Change

The onDateChange function is called when the user changes a date using the calendar widget in the DatePicker component.

Chosen Date:

Date

April 2025

S	M	T	W	T	F	S

import React from 'react';

import { DatePicker } from 'react-magma-dom';

export function Example() {
  const [chosenDate, setChosenDate] = React.useState<Date | undefined>(
    undefined
  );

  function handleDateChange(newChosenDate: Date) {
    setChosenDate(newChosenDate);
  }

  return (
    <div>
      <p>
        <strong>Chosen Date: </strong>
        {chosenDate && (
          <span>
            {`${
              chosenDate.getMonth() + 1
            }/${chosenDate.getDate()}/${chosenDate.getFullYear()}`}
          </span>
        )}
      </p>
      <DatePicker labelText="Date" onDateChange={handleDateChange} />
    </div>
  );
}

Focus Events

Is Focused?: No

Date

April 2025

S	M	T	W	T	F	S

import React from 'react';

import { DatePicker } from 'react-magma-dom';

export function Example() {
  const [isFocused, updateIsFocused] = React.useState<boolean>(false);

  function handleInputBlur(event: React.FocusChangeHandler) {
    updateIsFocused(false);
  }

  function handleInputFocus(event: React.FocusChangeHandler) {
    updateIsFocused(true);
  }

  return (
    <div>
      <p>
        <strong>Is Focused?: </strong>
        {isFocused ? 'Yes' : 'No'}
      </p>
      <DatePicker
        onInputBlur={handleInputBlur}
        onInputFocus={handleInputFocus}
        labelText="Date"
      />
    </div>
  );
}

On Change

The onChange event is called in multiple instances when internal values are changed and can be used as a generic state change event when you do not want to use each function separately.

onInputChange: The value parameter will return a string. If it is not what we consider a valid date, it will simply be the string typed in to the input (ie: 01/21). If we consider the input value to be a valid date, it will be the ISO string representation of the date entered.
onDateChange: The value parameter will return the ISO string representation of the date chosen with the calendar widget.
onInputBlur: If the input value is considered a valid date the onChange function will be called with the ISO string representation of the date in the input being returned in the value argument of the function.

Changed Value:

Date

April 2025

S	M	T	W	T	F	S

import React from 'react';

import { DatePicker } from 'react-magma-dom';

export function Example() {
  const [changedValue, setChangedValue] = React.useState<string | Date>('');

  function handleChange(value: string | Date, event: React.EventChangeHandler) {
    setChangedValue(value);
  }

  return (
    <div>
      <p>
        <strong>Changed Value: </strong>
        {changedValue}
      </p>
      <DatePicker onChange={handleChange} labelText="Date" />
    </div>
  );
}

Keyboard Navigation

The DatePicker is keyboard navigable for allowing the user to navigate between days, weeks, and months.

Date

April 2025

S	M	T	W	T	F	S

import React from 'react';

import { DatePicker } from 'react-magma-dom';

export function Example() {
  return <DatePicker labelText="Date" />;
}

Custom Styles

Custom styles can be passed into the datePicker component. The containerStyle prop will apply to the container; the inputStyle prop will apply to the input field. The labelStyle prop will apply to the field's label; the messageStyle prop will apply to the helper/error message. Please use discretion when adding custom styles.

Date

Please fix the error

April 2025

S	M	T	W	T	F	S

import React from 'react';

import { DatePicker } from 'react-magma-dom';

export function Example() {
  return (
    <DatePicker
      containerStyle={{
        border: '2px solid green',
        maxWidth: '300px',
        padding: '2px',
      }}
      errorMessage="Please fix the error"
      inputStyle={{ border: '1px dashed purple', borderRadius: '0' }}
      labelStyle={{ border: '1px dotted blue' }}
      labelText="Date"
      messageStyle={{ border: '1px solid black', padding: '' }}
    />
  );
}

Internationalization

To use a separate locale import a date-fns locale object (import { es } from 'date-fns/locale') and pass it in to the I18nContext provider.

Full example of internationalization override options

Español

Abril 2025

D	L	M	M	J	V	S

import React from 'react';

import { es } from 'date-fns/locale';
import { DatePicker, I18nContext, defaultI18n } from 'react-magma-dom';

export function Example() {
  return (
    <I18nContext.Provider
      value={{
        ...defaultI18n,
        days: {
          ...defaultI18n.days,
          min: {
            sunday: 'D',
            monday: 'L',
            tuesday: 'M',
            wednesday: 'M',
            thursday: 'J',
            friday: 'V',
            saturday: 'S',
          },
          long: {
            sunday: 'Domingo',
            monday: 'Lunes',
            tuesday: 'Martes',
            wednesday: 'Miércoles',
            thursday: 'Jueves',
            friday: 'Viernes',
            saturday: 'Sábado',
          },
        },
        datePicker: {
          ...defaultI18n.datePicker,
          calendarIconAriaLabel: 'Calendario',
          calendarOpenAnnounce:
            'El widget de calendario ahora está abierto. Presione la tecla de signo de interrogación para obtener los atajos de teclado para cambiar las fechas.',
          calendarCloseAriaLabel: 'Cerrar calendario',
          previousMonthAriaLabel: 'Mes Anterior',
          nextMonthAriaLabel: 'Próximo Mes',
          disabledDayAriaLabel: 'No disponible. ',
          selectedDayAriaLabel: '(Seleccionado)',
        },
        locale: es,
      }}
    >
      <DatePicker labelText="Español" />
    </I18nContext.Provider>
  );
}

Date Picker Props

This component uses forwardRef. The ref is applied to the Date Picker input element.

All of the standard input attributes can be provided as props and will be applied to the input element that gets rendered.

containerStyle

Description

Style properties for the component container element

Type

CSSProperties

Default

defaultDate

Description

Default selected date value

Type

Date

Default

errorMessage

Description

Content of the error message. If a value is provided, the component will be styled to show an error state

Type

React.ReactNode

Default

helperMessage

Description

Content of the helper message

Type

React.ReactNode

Default

inputStyle

Description

Style properties for the input element

Type

CSSProperties

Default

isClearable

Description

Clear contents of input by clicking a clear button

Type

boolean

Default

false

isInverse

Description

If true, the component will have inverse styling to better appear on a dark background

Type

boolean

Default

false

labelStyle

Description

Style properties for the label element

Type

CSSProperties

Default

labelText

Required

Description

Text for label

Type

React.ReactNode

Default

maxDate

Description

Maximum date allowed to be chosen in the calendar

Type

Date

Default

messageStyle

Description

Style properties for the helper or error message

Type

CSSProperties

Default

minDate

Description

Minimum date allowed to be chosen in the calendar

Type

Date

Default

onChange

Description

Event fired in multiple instances when internal values are changed and can be used as a generic state change event

Type

function

Default

onDateChange

Description

Event that will fire when day is changed

Type

function

Default

onInputBlur

Description

Event that will fire when the text input loses focus

Type

function

Default

onInputChange

Description

Event that will fire when the text input is changed

Type

function

Default

onInputFocus

Description

Event that will fire when the text input gains focus

Type

function

Default

placeholder

Description

Text for input placeholder

Type

string

Default

required

Description

If true, this component must have a value

Type

boolean

Default

false

value

Description

Value of the date input, used when setting the date value externally

Type

Date

Default

On this page

Design

Components

Intro

API

Patterns

Data Visualization

Date Picker

Basic Usage

Default Date

Value

Minimum and Maximum Dates

Clearing the Date

Placeholder Text

Helper Message

Error Message

Inverse

Date Formats

Events

On Input Change

On Date Change

Focus Events

On Change

Keyboard Navigation

Custom Styles

Internationalization

Date Picker Props