{"id":13515167,"url":"https://github.com/airblade/stimulus-datepicker","last_synced_at":"2025-04-09T23:17:38.092Z","repository":{"id":57676658,"uuid":"473284442","full_name":"airblade/stimulus-datepicker","owner":"airblade","description":"Stimulus-powered accessible datepicker","archived":false,"fork":false,"pushed_at":"2024-04-30T13:14:54.000Z","size":255,"stargazers_count":88,"open_issues_count":11,"forks_count":6,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-04-09T23:17:34.379Z","etag":null,"topics":["datepicker","stimulus","stimulusjs"],"latest_commit_sha":null,"homepage":"https://airblade.github.io/stimulus-datepicker/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/airblade.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-03-23T17:08:59.000Z","updated_at":"2025-04-09T16:58:10.000Z","dependencies_parsed_at":"2022-09-02T15:02:41.713Z","dependency_job_id":"2e0814a3-7d71-4a66-9573-501adc49abd6","html_url":"https://github.com/airblade/stimulus-datepicker","commit_stats":{"total_commits":106,"total_committers":2,"mean_commits":53.0,"dds":"0.028301886792452824","last_synced_commit":"b27eac57eeb5d04228c2ab7219585ca8a5e7e194"},"previous_names":[],"tags_count":19,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/airblade%2Fstimulus-datepicker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/airblade%2Fstimulus-datepicker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/airblade%2Fstimulus-datepicker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/airblade%2Fstimulus-datepicker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/airblade","download_url":"https://codeload.github.com/airblade/stimulus-datepicker/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248125593,"owners_count":21051771,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["datepicker","stimulus","stimulusjs"],"created_at":"2024-08-01T05:01:07.047Z","updated_at":"2025-04-09T23:17:38.067Z","avatar_url":"https://github.com/airblade.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"# Stimulus Datepicker\n\nThis is a Stimulus-powered datepicker which:\n\n- localises and parses dates in the input field according to the strftime directives you configure;\n- presents a calendar closely adhering to the [WAI-ARIA date picker dialog](https://www.w3.org/TR/wai-aria-practices/examples/dialog-modal/datepicker-dialog.html) design pattern;\n- sends the date back to the server in ISO8601 format (YYYY-MM-DD).\n\nPlease see the [demo page](https://airblade.github.io/stimulus-datepicker/) for a few simple examples.\n\nYour server produces an ISO8601 date; your user interacts with it in the format you configured and/or via the popup calendar; the form sends the date back to the server in ISO format.\n\nMonth and day names are generated in the user's locale.  Button titles and ARIA labels are customisable, e.g. for localisation.\n\nDates are local; no timezones or daylight savings are involved.\n\nYou can easily adjust the calendar's appearance via CSS custom properties or just overriding the CSS classes.\n\nSize: JS 3.6kB minified and gzipped, CSS 2.7kB gzipped.\n\n\u003cimg src=\"https://github.com/airblade/stimulus-datepicker/raw/main/screenshot.png\" width=\"296px\"\u003e\n\n\n## Installation\n\nThe project contains JavaScript and CSS.  If you only use importmaps, i.e. you don't use jsbundling-rails or cssbundling-rails, first install the JavaScript:\n\n```\nbin/importmap pin stimulus-datepicker\n```\n\nAnd then add a link to the stylesheet to your view:\n\n```\n\u003clink rel=\"stylesheet\" href=\"https://unpkg.com/stimulus-datepicker@1.0.5/css/datepicker.css\" data-turbo-track=\"reload\"\u003e\n```\n\nIf you use jsbundling-rails or cssbundling-rails, follow their instructions for installing packages.\n\nThen register the datepicker controller with your Stimulus application:\n\n```diff\n  // app/javascript/controllers/application.js\n\n  import { Application } from '@hotwired/stimulus'\n+ import { Datepicker } from 'stimulus-datepicker'\n\n  const application = Application.start()\n+ application.register('datepicker', Datepicker)\n```\n\n## Usage\n\nTo use the datepicker, wrap your input field with a controller div.\n\n```html\n\u003cdiv data-controller=\"datepicker\"\u003e\n  \u003cinput data-datepicker-target=\"input\" type=\"text\" name=\"foobar\" value=\"2022-03-23\"/\u003e\n  \u003cspan data-datepicker-target=\"toggle\"\u003ecalendar\u003c/span\u003e\n\u003c/div\u003e\n```\n\nYour calendar icon or equivalent must have the data attribute `data-datepicker-target=\"toggle\"`.\n\nThe input field:\n\n- must have the data attribute `data-datepicker-target=\"input\"`;\n- should have `type=\"text\"`, not `type=\"date\"`, to avoid conflicting with built-in browser functionality;\n- must have a `name`;\n- its `value`, if given, must be a YYYY-MM-DD date string.\n\n\n## Configuration\n\nYou can configure your datepicker with the following attributes.  Declare them on your controller as `data-datepicker-[name]-value`.\n\n| Name | Default | Description |\n|--|--|--|\n| `format` | `\"%Y-%m-%d\"` | Format for the date in the input field (see below). |\n| `first-day-of-week` | `1` | First day of the week in the calendar (Sunday is `0`). |\n| `day-name-length` | `2` | Length of the abbreviated day names in the calendar, e.g. \"Mo\". |\n| `allow-weekends` | `\"true\"` | Whether weekends are selectable. |\n| `month-jump` | `\"dayOfMonth\"` | When jumping to the previous/next month, whether to go to the same day of the month (`\"dayOfMonth\"`) or the same day of the week (`\"dayOfWeek\"`). |\n| `min` | `\"\"` | The earliest choosable date (YYYY-MM-DD). |\n| `max` | `\"\"` | The latest choosable date (YYYY-MM-DD). |\n| `underflow-message` | `\"\"` | Client-side form validation message when the selected date is earlier than the `min` date.  `%s` is replaced with the formatted min date.  E.g. `\"Date must be %s or later.\"` |\n| `overflow-message` | `\"\"` | Client-side form validation message when the selected date is later than the `max` date.  `%s` is replaced with the formatted max date.  E.g. `\"Date must be %s or earlier.\"` |\n| `disallow` | `[]` | Dates which cannot be selected.  E.g. `[\"2022-12-25\", \"2023-01-01\"]` |\n| `text` | \u003cpre\u003e{\u003cbr\u003e  underflow:     \"\",\u003cbr\u003e  overflow:      \"\",\u003cbr\u003e  previousMonth: \"Previous month\",\u003cbr\u003e  nextMonth:     \"Next month\",\u003cbr\u003e  today:         \"Today\",\u003cbr\u003e  chooseDate:    \"Choose Date\",\u003cbr\u003e  changeDate:    \"Change Date\"\u003cbr\u003e}\u003c/pre\u003e | User-facing text.  The value object is merged into the defaults.\u003cbr\u003e\u003cul\u003e\u003cli\u003e_underflow_:  client-side form validation message when the selected date is earlier than the `min` date.  `%s` is replaced with the formatted min date.  E.g. `\"Date must be %s or later.\"`\u003c/li\u003e\u003cli\u003e_overflow_: client-side form validation message when the selected date is later than the `max` date.  `%s` is replaced with the formatted max date.  E.g. `\"Date must be %s or earlier.\"`\u003c/li\u003e\u003cli\u003e_previousMonth_, _nextMonth_, _today_: button titles and ARIA labels\u003c/li\u003e\u003cli\u003e_chooseDate_, _changeDate_: ARIA labels\u003c/li\u003e\u003c/ul\u003e  |\n| `locales` | `[\"default\"]` | Locale for month and day names, along with fallbacks.  Use BCP 47 language tags.  E.g. `[\"de-DE\", \"default\"]`. |\n\nYou can use the following strftime directives in `data-datepicker-format-value`:\n\n| Directive | Meaning |\n|--|--|\n| `%d` | Day of the month, zero-padded (01..31) |\n| `%-d` | Day of the month, no padding (1..31) |\n| `%m` | Month of the year, zero-padded (01..12) |\n| `%-m` | Month of the year, no padding (1..12) |\n| `%B` | The full month name in the browser's locale (January) |\n| `%b` | The abbreviated month name in the browser's locale (Jan) |\n| `%Y` | Full year, four digits (2022) |\n| `%y` | Year in 21st Century, two digits (22) |\n\n\n## Keyboard support\n\nThe datepicker is fully navigable by keyboard.  In addition to the WAI-ARIA keys, you can also use Vim-style movement keys.\n\n### Toggle target (your calendar icon)\n\n| Key | Result |\n|--|--|\n| \u003ckbd\u003eSpace\u003c/kbd\u003e, \u003ckbd\u003eEnter\u003c/kbd\u003e | \u003cul\u003e\u003cli\u003eOpen the datepicker dialog.\u003c/li\u003e\u003cli\u003eMove focus to selected date, i.e. the date displayed in the input text field.  If no date has been selected, focus on the current date.\u003c/li\u003e\u003c/ul\u003e |\n\n### Datepicker dialog (the calendar)\n\n| Key | Result |\n|--|--|\n| \u003ckbd\u003eEscape\u003c/kbd\u003e | Close the dialog and return focus to the toggle target. |\n| \u003ckbd\u003eTab\u003c/kbd\u003e | \u003cul\u003e\u003cli\u003eMove focus to next element in the dialog's tab sequence.\u003c/li\u003e\u003cli\u003eThe dialog \"traps\" focus so if focus is on the last item, move focus to the first.\u003c/ul\u003e |\n| \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eTab\u003c/kbd\u003e | \u003cul\u003e\u003cli\u003eMove focus to previous element in the dialog's tab sequence.\u003c/li\u003e\u003cli\u003eThe dialog \"traps\" focus so if focus is on the first item, move focus to the last.\u003c/ul\u003e |\n\n### Previous-month / today / next-month Buttons\n\n| Key | Result |\n|--|--|\n| \u003ckbd\u003eSpace\u003c/kbd\u003e, \u003ckbd\u003eEnter\u003c/kbd\u003e | Change the month displayed in the calendar grid. |\n\n### Date grid\n\n| Key | Result |\n|--|--|\n| \u003ckbd\u003eSpace\u003c/kbd\u003e, \u003ckbd\u003eEnter\u003c/kbd\u003e | Select the date, close the dialog, move focus to the toggle target. |\n| \u003ckbd\u003eUp Arrow\u003c/kbd\u003e, \u003ckbd\u003ek\u003c/kbd\u003e | Move focus to the same day of the previous week. |\n| \u003ckbd\u003eDown Arrow\u003c/kbd\u003e, \u003ckbd\u003ej\u003c/kbd\u003e | Move focus to the same day of the next week. |\n| \u003ckbd\u003eRight Arrow\u003c/kbd\u003e, \u003ckbd\u003el\u003c/kbd\u003e | Move focus to the next day. |\n| \u003ckbd\u003eLeft Arrow\u003c/kbd\u003e, \u003ckbd\u003eh\u003c/kbd\u003e | Move focus to the previous day. |\n| \u003ckbd\u003eHome\u003c/kbd\u003e, \u003ckbd\u003e^\u003c/kbd\u003e, \u003ckbd\u003e0\u003c/kbd\u003e | Move focus to the first day of the current week. |\n| \u003ckbd\u003eEnd\u003c/kbd\u003e, \u003ckbd\u003e$\u003c/kbd\u003e | Move focus to the last day of the current week. |\n| \u003ckbd\u003ePage Up\u003c/kbd\u003e, \u003ckbd\u003eb\u003c/kbd\u003e | Change the grid of dates to the previous month and focus on the corresponding\u003csup\u003e*\u003c/sup\u003e date one month earlier. |\n| \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003ePage Up\u003c/kbd\u003e, \u003ckbd\u003eB\u003c/kbd\u003e | Change the grid of dates to the previous year and focus on the same date one year earlier. |\n| \u003ckbd\u003ePage Down\u003c/kbd\u003e, \u003ckbd\u003ew\u003c/kbd\u003e | Change the grid of dates to the next month and focus on the corresponding\u003csup\u003e*\u003c/sup\u003e date one month later. |\n| \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003ePage Down\u003c/kbd\u003e, \u003ckbd\u003eW\u003c/kbd\u003e | Change the grid of dates to the next year and focus on the same date one year later. |\n\n\u003csup\u003e*\u003c/sup\u003e The corresponding date in the adjacent month depends on `data-datepicker-month-jump-value`:\n\n- `\"dayOfMonth\"`: the corresponding date is the same date, e.g. 7th;\n- `\"dayOfWeek\"`: the corresponding date is the same day of the week, four weeks earlier/later.\n\n\n## CSS\n\nYou can alter the appearance of the calendar by setting these custom properties, or of course by just overriding the CSS classes.\n\n| Property | Default | Description |\n|--|--|--|\n| `--sdp-selected` | `#005fcc` | Background colour of selected date; colour of date focus ring. |\n| `--sdp-selected-invert` | `#ffffff` | Colour of selected date. |\n| `--sdp-prev-month` | `#888888` | Colour of dates in the previous month. |\n| `--sdp-next-month` | `#888888` | Colour of dates in the next month. |\n| `--sdp-disabled` | `#1010104d` | Colour of disabled dates; background color of selected date when disabled. |\n| `--sdp-disabled-invert` | `#ffffff` | Colour of selected date when disabled. |\n| `--sdp-background` | `#ffffff` | Background colour. |\n| `--sdp-border` | `#dddddd` | Border colour. |\n| `--sdp-shadow` | `0deg 0% 50%` | Box shadow colour (hsl). |\n| `--sdp-icon` | `#4a4a4acc` | Colour of the icons, e.g. previous-month button. |\n| `--sdp-nav-button-background` | `#f5f5f5` | Background colour of the navigation buttons. |\n| `--sdp-nav-button-background-hover` | `#eeeeee` | Background colour on hover of the navigation buttons. |\n| `--sdp-days-of-week` | `#4a4a4a` | Colour of the days of the week. |\n\n\n## Intellectual Property\n\nThis package is copyright Andrew Stewart.\n\nThis package is available as open source under the terms of the MIT licence.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fairblade%2Fstimulus-datepicker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fairblade%2Fstimulus-datepicker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fairblade%2Fstimulus-datepicker/lists"}