\n
\n Pointer and keyboard, both fully supported — recorded from the real component.\n
\n\n\n\n\n Every state below is a live story: pick dates, tab through it, toggle props.\n
\n\n- Built on [react-datepicker](https://github.com/Hacker0x01/react-datepicker) 9\n- Written in TypeScript; declarations are generated from source and ship with the package\n- Works with React 18 and 19, in both ESM and CommonJS, and renders on the server\n- No runtime dependency on the deprecated `@hig/*` packages\n- Zero known vulnerabilities in runtime dependencies\n\n## Install\n\n```sh\nnpm install react-hig-datepicker\n```\n\nReact and React DOM are peer dependencies:\n\n```sh\nnpm install react react-dom\n```\n\n## Usage\n\n```jsx\nimport { useState } from \"react\";\nimport DatePicker from \"react-hig-datepicker\";\nimport \"react-hig-datepicker/styles.css\";\n\nexport default function Example() {\n const [date, setDate] = useState(null);\n\n return (\n![\"An](\"https://raw.githubusercontent.com/ziweiwu/react-date-picker/master/docs/images/field-default.png\")
|\n| **With a value** — the label floats up and the clear button appears.![\"A](\"https://raw.githubusercontent.com/ziweiwu/react-date-picker/master/docs/images/field-filled.png\")
|\n| **Keyboard focus** — a visible ring, in addition to the blue underline.![\"The](\"https://raw.githubusercontent.com/ziweiwu/react-date-picker/master/docs/images/field-focused.png\")
|\n| **Helper text** — linked to the input with `aria-describedby`.![\"A](\"https://raw.githubusercontent.com/ziweiwu/react-date-picker/master/docs/images/field-instruction.png\")
|\n| **Disabled** — dashed underline, muted label and icon.![\"A](\"https://raw.githubusercontent.com/ziweiwu/react-date-picker/master/docs/images/field-disabled.png\")
|\n| **Hover** — days highlight in HIG blue; today stays bold blue.![\"The](\"https://raw.githubusercontent.com/ziweiwu/react-date-picker/master/docs/images/calendar-hover.png\")
|\n| **Open calendar** — squared day cells, today in bold blue, the selection filled.![\"A](\"https://raw.githubusercontent.com/ziweiwu/react-date-picker/master/docs/images/calendar-open.png\")
|\n\nScreenshots are generated by `npm run screenshots` and the animation above by\n`npm run demo:gif`. Both freeze the browser clock, so the images stay identical\nbetween runs instead of drifting with the current month.\n\n### Styling from Sass\n\nThe Sass sources ship with the package, so you can override HIG tokens before\nthe stylesheet is generated:\n\n```scss\n@use \"react-hig-datepicker/src/styles/datePicker\";\n```\n\n## Props\n\nEvery [react-datepicker prop](https://reactdatepicker.com) is forwarded, with\nthe exceptions noted under *Reserved* below. The additions are:\n\n| Prop | Type | Default | Description |\n| ------------------ | ----------------------- | -------------- | -------------------------------------------------------------- |\n| `label` | `string` | — | Floating label text. |\n| `showLabel` | `boolean` | `true` | Render the label. |\n| `instruction` | `string` | — | Helper text below the field, linked via `aria-describedby`. |\n| `showInstruction` | `boolean` | `false` | Render the helper text. |\n| `errors` | `ReactNode` | — | Validation message; also sets `aria-invalid` and error styling. |\n| `placeholder` | `string` | — | Input placeholder. |\n| `showIcon` | `boolean` | `true` | Show the HIG calendar icon. |\n| `showClearButton` | `boolean` | `false` | Show a clear button once a date is selected. |\n| `clearButtonTitle` | `string` | `\"Clear date\"` | Accessible name and tooltip for the clear button. |\n| `closeOnSelect` | `boolean` | `true` | Close the calendar after a day is picked. |\n| `focused` | `boolean` | — | Controlled override for the field's focused styling. |\n| `disabled` | `boolean` | `false` | Disable the field. |\n| `selected` | `Date \\| null` | — | The selected date. |\n| `onChange` | `(date, event) => void` | — | Called with a `Date`, or `null` when cleared. |\n| `id` | `string` | auto | Input id. A unique one is generated when omitted. |\n\n`selected`, `minDate`, `maxDate`, `startDate`, `endDate`, `excludeDates`,\n`includeDates` and `highlightDates` all accept a `Date`, a date string, a\ntimestamp, or any object with a `toDate()` method (moment, dayjs).\n\n**Reserved.** `customInput`, `isClearable`, `popperModifiers`,\n`popperPlacement` and `withPortal` are controlled by this component to keep the\nHIG presentation intact.\n\nTypeScript declarations are generated from the source and bundled; no `@types`\npackage is needed. Range and multi-date selection are not supported, so\n`selectsRange` and `selectsMultiple` are rejected at compile time.\n\n## Accessibility\n\nThe component is verified against WCAG 2.1 AA on every run, with axe in jsdom\n(unit tests) and in a real browser (`npm run test:e2e`, which also checks\ncolour contrast).\n\n- The field is a focusable, read-only combobox — typing is disabled, but it is\n reachable by Tab and opens with Enter/↓.\n- Labels and helper text are programmatically associated with the input, and\n each instance gets a unique id.\n- All interactive elements have a visible `:focus-visible` indicator.\n- The palette meets AA contrast minimums, and the calendar has a\n `forced-colors` (high-contrast) treatment.\n- The label transition is disabled under `prefers-reduced-motion`.\n\n## Behaviour\n\n[`INVARIANTS.md`](./INVARIANTS.md) specifies what the component is expected to\ndo — value coercion, calendar interaction, the clear button, labelling and\naccessibility — with each statement tagged by the test that enforces it.\n\n## Development\n\n```sh\nnpm install\nnpm start # demo at http://localhost:5173\nnpm test # unit tests (Vitest + Testing Library)\nnpm run test:e2e # browser tests (Playwright + axe)\nnpm run lint\nnpm run typecheck # type-checks the whole project\nnpm run build # -> es/, lib/, css/\nnpm run screenshots # regenerate docs/images/ used by this README\nnpm run demo:gif # re-record docs/images/demo.gif (needs ffmpeg)\n```\n\n## Upgrading from 0.1.x\n\n0.1.x could not be installed alongside React 17+ — its `@hig/*` dependencies\nwere peer-locked to React 15/16 — so 1.0 replaces that chain. Migration is\nusually two changes.\n\n### 1. Dates are native `Date` objects, not moment\n\nreact-datepicker 9 dropped moment. `onChange` now hands you a `Date`:\n\n```diff\n-onChange={(date) => setDate(date)} // date was a moment\n-{date.format(\"YYYY-MM-DD\")}\n+onChange={(date) => setDate(date)} // date is a Date, or null\n+{date?.toISOString().slice(0, 10)}\n```\n\nValues you *pass in* still accept moment objects, so `selected={moment()}`\nkeeps working — only values you receive changed.\n\nDate format strings are now [date-fns](https://date-fns.org/docs/format)\npatterns rather than moment ones. Most notably `YYYY` becomes `yyyy` and `DD`\nbecomes `dd`. `locale` now takes a date-fns locale object rather than a string.\n\n### 2. Import the stylesheet explicitly\n\n0.1.x pulled in `@hig/text-field`'s CSS as a side effect of importing the\ncomponent, and the `lib/datePicker.css` the old README pointed at was never\nactually published. All styles now live in one file that you import yourself:\n\n```js\nimport \"react-hig-datepicker/styles.css\";\n```\n\n### Also worth knowing\n\n- **Fixed:** the input was previously rendered permanently `disabled`, which\n made it unreachable by keyboard and — via HIG's `--disabled` rule — meant\n `showClearButton` could never display anything. Both now work.\n- **Fixed:** every instance used the hardcoded id `hig__date-picker`, so\n multiple pickers on a page produced duplicate ids and broken label\n associations. Ids are now unique per instance.\n- **Fixed:** the stylesheet contained unscoped `input { … !important }` and\n `button { … }` rules that restyled unrelated elements in the host page.\n- **Changed:** several colours were darkened to reach AA contrast. The blues\n and teal keep their hue; only luminance moved. Tokens live in\n `src/styles/_tokens.scss`.\n- **Removed:** `propTypes`. React 19 ignores them at runtime; TypeScript\n declarations replace them.\n\n## Sponsor\n\nThis component is in low-maintenance mode — it works, but it is not under\nactive development. If it is load-bearing for you and you would like that to\nchange, [sponsorship](https://github.com/sponsors/ziweiwu) is the signal that\ngets it back on the list.\n\n## License\n\n[MIT](./LICENSE) © Ziwei Wu\n","readmeFilename":"README.md"}