1.0.1 • Published 10 months ago

@idesigncode/date-input v1.0.1

Weekly downloads
-
License
MIT
Repository
github
Last release
10 months ago

@idesigncode/date-input

An ESM date input component with a composable datepicker UI for React.

Features

  • Calendar datepicker UI for date selection.
  • Composable components for flexible customisation (optional).
  • Customisable display and value formats (as per date-fns format).
  • Maximum/minimum date range.
  • Uses the Constraint Validation API to setCustomValidity (with optional message customisation).
  • User typing support.
  • ARIA screen reader support.
  • Keyboard navigation support with Tab, Space/Enter & Esc/Escape keys.
  • Locale support for internationalisation.
  • Inherited text direction support for "RTL" (Right To Left) written languages.
  • Light & dark themes with prefers-color-scheme.
  • React controlled component.

Examples

Check out the Storybook docs for working examples.

Install

Update/install the peer dependencies as needed.

Install the package:

npm i @idesigncode/date-input

Basic usage

Here is a basic example of how to set up the component:

import React from 'react';
import DateInput from '@idesigncode/date-input/DateInput.mjs';
import '@idesigncode/date-input/theme.css';
import '@idesigncode/date-input/layout.css';

const BasicUsage = () => {
  const [value, setValue] = React.useState('');

  const handleOnChange = (event, formatValue) => {
    setValue(formatValue);
  };

  return (
    <DateInput name="field_name" onChange={handleOnChange} value={value} />
  );
};

export default BasicUsage;

For more information see the Required Props example.

Composable usage

If you want further customisation of the components you can compose them yourself:

import React from 'react';
import '@idesigncode/date-input/theme.css';
import Calendar from '@idesigncode/date-input/Calendar.mjs';
import '@idesigncode/date-input/Calendar.css';
import CalendarArrow from '@idesigncode/date-input/CalendarArrow.mjs';
import '@idesigncode/date-input/CalendarArrow.css';
import DateInput from '@idesigncode/date-input/DateInput.mjs';
import '@idesigncode/date-input/DateInput.css';
import CalendarTabs from '@idesigncode/date-input/CalendarTabs.mjs';
import '@idesigncode/date-input/CalendarTabs.css';
import Field from '@idesigncode/date-input/Field.mjs';
import '@idesigncode/date-input/Field.css';
import View from '@idesigncode/date-input/View.mjs';
import '@idesigncode/date-input/View.css';
import ViewBody from '@idesigncode/date-input/ViewBody.mjs';
import '@idesigncode/date-input/ViewBody.css';
import ViewHead from '@idesigncode/date-input/ViewHead.mjs';
import '@idesigncode/date-input/ViewHead.css';
import ViewWeekDays from '@idesigncode/date-input/ViewWeekDays.mjs';
import '@idesigncode/date-input/ViewWeekDays.css';

const ComposableUsage = () => {
  const [value, setValue] = React.useState('');

  const handleOnChange = (event, formatValue) => {
    setValue(formatValue);
  };

  return (
    <DateInput name="field_name" onChange={handleOnChange} value={value}>
      <Field />
      <Calendar>
        <CalendarArrow />
        <CalendarTabs />
        <View>
          <ViewHead />
          <ViewBody>
            <ViewWeekDays />
          </ViewBody>
        </View>
      </Calendar>
    </DateInput>
  );
};

export default ComposableUsage;

For more information about composable usage, please see the props/children example.

Styling

The CSS (themes) & CSS (layout) are exported for use via stylesheets. It is best to declare these default styles before your own styles.

You can also supply your own pre-styled component for the input field with the as prop (see the props/as documentation for more information).

Validation

Validation of the value is performed with the displayFormat, format, max, min and required props (if given).

This validation occurs during the input field's onInput event, and also on initial load (if there is a given value).

For more information about validation, please see the Validation example.

You can also set your own custom validity messages with the onValidationMessage prop (see the props/onValidationMessage example).

Accessibility

ARIA attributes are used to provide screen reader support.

All interactive elements are keyboard accessible by using the standard Tab & Space/Enter key navigation. The Esc/Escape key can also be used to close the <Calendar /> while open.

Upon the user opening the <Calendar />, either the selected date or first selectable date recieves :focus.

Required props

PropTypeDescription
namestringStandard HTML attribute for the field name.
onChangefuncA function for custom handling of onChange events. Receives the input field's onChange event and the formatValue (formatted as per format).
valuestringA date string formatted as per the format prop or an empty string.

Note: It is recommended to update your local state with the formatValue rather than the event.target.value.

Optional props

PropTypeDefaultDescription
aselementType OR stringCustomise the input field with either a custom component or an HTML element.
classNamestringCan be directly given to each component.
disabledboolDisable the input field and prevent calendar opening.
displayFormatstringdd/MM/yyyyThe date-fns format of the selected date when displayed to the user. This also becomes the placeholder text (lowercase).
formatstringyyyy-MM-ddThe date-fns format of the max, min and value props. Also formats the formatValue returned from the onChange function.
initialViewstringDayThe view to open the calendar to (either Day, Month or Year).
localeobjecten-AUThe date-fns locale object used for formatting and text translation.
maxstringA date string formatted as per the format prop. This will prevent the user selecting a date after this date.
minstringA date string formatted as per the format prop. This will prevent the user selecting a date before this date.
onValidationMessagefunctionA function for custom handling of validation messages. Receives an error message string (due to an invalid value) or an empty string from the input field's onInput event.
openboolfalseShows the <Calendar /> on initial load.
refref objectA React ref for referencing the input field. This must only be applied to the <DateInput /> component.
requiredboolStandard HTML attribute for specifying a value is required.
...HTML attributesThese will be passed to the input field unless they are reserved for use within the component.

Resources

License

MIT

1.0.1

10 months ago

1.0.0

11 months ago

0.0.1

11 months ago