Input I18n

Inputs all include robust multiple language support, with additional locale support for date, time, and number inputs. Complex locale supprt is abstracted into localizers, making it easy to use inputs with whichever date or i18n library you want.

Messages

Most inputs include some amount natural language: button text, ARIA-labels, etc. Each string is customizable per component with their messages prop. They can also be configured for all components via a Localization Provider, rendered near your app's root.

<Localization

messages={{

moveToday: "Today",

moveBack: "Navigate back",

moveForward: "Navigate forward",

emptyList: "There are no items in this list",

emptyFilter: "The filter returned no results",

}}

>

{...}

</Localization>

You can still override messages at the component level wih the messages prop.

Read direction

Each input repects the dir attribute for controlling the read direction.

const [direction, setDirection] = useState("rtl"); <> <div className="mb-10"> <label> <input type="radio" value="rtl" name="direction" onChange={(e) => setDirection("rtl")} defaultChecked /> Right to left </label> <label> <input type="radio" value="ltr" name="direction" onChange={(e) => setDirection("ltr")} /> Left to right </label> </div> <div dir={direction} className="flex space-y-4 max-w-xs"> <Calendar defaultValue={new Date()} valueFormat={{ month: "short", day: "2-digit", year: "numeric", }} /> <NumberPicker defaultValue={1305043} format={{ style: "currency", currency: "USD" }} /> <Multiselect data={[ "JavaScript", "ML", "Scripting", "CSS", "HTML", ]} defaultValue={["CSS", "HTML"]} /> </div> </>;

const [direction, setDirection] = useState("rtl");
<>
  <div className="mb-10">
    <label>
      <input
        type="radio"
        value="rtl"
        name="direction"
        onChange={(e) => setDirection("rtl")}
        defaultChecked
      />
      Right to left
    </label>
    <label>
      <input
        type="radio"
        value="ltr"
        name="direction"
        onChange={(e) => setDirection("ltr")}
      />
      Left to right
    </label>
  </div>
  <div dir={direction} className="flex space-y-4 max-w-xs">
    <Calendar
      defaultValue={new Date()}
      valueFormat={{
        month: "short",
        day: "2-digit",
        year: "numeric",
      }}
    />
    <NumberPicker
      defaultValue={1305043}
      format={{ style: "currency", currency: "USD" }}
    />
    <Multiselect
      data={[
        "JavaScript",
        "ML",
        "Scripting",
        "CSS",
        "HTML",
      ]}
      defaultValue={["CSS", "HTML"]}
    />
  </div>
</>;

Date and number formatting

Locale specific date and number formatting handled using JavaScript's Intl API. These localizers are enabled by default, but can be configured directly if needed.

import { DateLocalizer, NumberLocalizer } from 'react-widgets/IntlLocalizer';

<Localization

date={new DateLocalizer({ culture: 'en-BG', firstOfWeek: 1 })}

number={new NumberLocalizer({ culture: 'en-BG' })}

messages={...}

>

{...}

</Localization>

Note that the date localizer includes a firstOfWeek parameter. It's not currently possible to infer this value with the use of the Intl API, so needs to be provided seperately. Other localizers do not require this.

Heads up

Intl provides robust date and number formatting API's but no control over locale based parsing. Instead, new Date and parseFloat are used to parse values back from string. If you need more control over parsing, consider another localizer or provide a custom parse prop

Other Localizers

Additional localizers are supported as seperate package installs to not bloat the core library when not used.

Moment.js date

npm install moment react-widgets-moment --save

See the official Moment docs for information on integrating Moment into your build pipeline effectively.

import moment from 'moment'

import MomentLocalizer from 'react-widgets-moment';

import DatePicker from 'react-widgets/DatePicker';

moment.locale('en')

const localizer = new MomentLocalizer(moment)

<Localization date={momentLocalizer}>

Moment format props accept strings

<DatePicker format="mmm YYY" />

date-fns date

npm install react-widgets-date-fns date-fns@2.0.0 --save

See the official date-fns docs for information on integrating date-fns.

The date-fns localizer is a convenient option to get up and running quickly as it is ready-to-use with the en-US locale without any configuration, and includes only the date-fns bits that are used for formatting and parsing dates so the additional bundle size should be minimal.

import DateFnsLocalizer from "react-widgets-date-fns";

import DatePicker from "react-widgets/DatePicker";

<Localization date={new DateFnsLocalizer()}>

...

</Localization>;

Additional locales can be included and date formats overridden by passing them as options to the localizer function.

// Use custom date formats and include all date-fns locales

import DateFnsLocalizer, {

defaultFormats,

} from "react-widgets-date-fns";

import locales from "date-fns/locale";

const formats = Object.assign(defaultFormats, {

default: "mmm YY",

});

const localizer = new DateFnsLocalizer({

formats,

locales,

});

// Include only the locales you need to limit bundle size

import enGB from "date-fns/locale/en-GB";

import de from "date-fns/locale/de";

new DateFnsLocalizer({

locales: { "en-GB": enGB, de: de },

});

date-fns format props accept strings

<DatePicker format="mmm YYY" />

Simple Number number

The simple-number localizer provides a minimal token based number formatting and parsing strategy. Its best when you don't need robust locale support for currencies, and numbers;

import SimpleNumberLocalizer from 'react-widgets-simple-number';

import NumberPicker from 'react-widgets/NumberPicker';

new SimpleNumberLocalizer()

<Localization number={new SimpleNumberLocalizer()}>

...

</Localization>

Check out the documentation for format-number-with-string for a complete guide to its format syntax.

<NumberPicker format="-$#,###.00" />

Creating a Localizer

New localizers are easy to create, either by sub-classing an existing one to customize it or by creating a new one entirely by implementing the Localizer interface for either Dates or Numbers.

Consult the source code and TypeScript types for details on what interface needs to be implemented.