diff --git a/.changeset/docs-datepicker-tomselect.md b/.changeset/docs-datepicker-tomselect.md new file mode 100644 index 000000000..568597b51 --- /dev/null +++ b/.changeset/docs-datepicker-tomselect.md @@ -0,0 +1,5 @@ +--- +"@tabler/docs": minor +--- + +Added docs pages for the Datepicker and Tom Select form plugins, `form-datepicker` and `form-select-tomselect`. diff --git a/docs/content/ui/forms/form-colorpicker.mdx b/docs/content/ui/forms/form-colorpicker.mdx index aff8712b5..5f5b1805f 100644 --- a/docs/content/ui/forms/form-colorpicker.mdx +++ b/docs/content/ui/forms/form-colorpicker.mdx @@ -3,6 +3,7 @@ title: Color picker summary: A color picker lets users pick a color from a gradient, a set of swatches, or by typing a value. Use it in theme settings, tag colors, and any field that stores a color. docs-libs: [coloris.js] description: Let users pick a color in a form. +related: [/ui/forms/form-datepicker] --- import Example from '@components/Example.astro'; import CdnImportPlugin from '@components/CdnImportPlugin.astro'; diff --git a/docs/content/ui/forms/form-datepicker.mdx b/docs/content/ui/forms/form-datepicker.mdx new file mode 100644 index 000000000..b96410c20 --- /dev/null +++ b/docs/content/ui/forms/form-datepicker.mdx @@ -0,0 +1,150 @@ +--- +title: Date picker +summary: A date picker lets users pick a date from a calendar instead of typing it by hand. Use it for booking forms, event dates, deadlines, or any field that expects a specific date. +docs-libs: [litepicker] +description: Let users pick a date from a calendar with the Litepicker plugin, as a plain input, an icon input, or an inline calendar. +related: [/ui/forms/form-elements, /ui/forms/form-colorpicker] +--- + +import Example from '@components/Example.astro'; +import CdnImportPlugin from '@components/CdnImportPlugin.astro'; +import TabsPackage from '@components/TabsPackage.astro'; +import Icon from '@ui/Icon.astro'; +import { Code } from 'astro:components'; +import { site } from '@shared/lib/site.ts'; + +## Overview + +The date picker is a normal text input with the [Litepicker](https://litepicker.com/) plugin attached. Litepicker opens a calendar when the field is focused and writes the picked date back into the input, so the field still works in a form like any other text field. + + + + + +## Installation + +Install Litepicker with npm: + + + +Or include it from a CDN: + +`} /> + +Tabler restyles the calendar to match the rest of the interface. Those styles live in the vendors plugin, so include `tabler-vendors.css` as well: + + + +## Usage + +### Basic input + +Add a text input with the `form-control` class, then attach Litepicker to it with its `element` option. + + + + + +```js +const picker = new Litepicker({ + element: document.getElementById('datepicker-basic'), +}); +``` + +### Icon input + +Wrap the field in `.input-icon` and add a calendar icon, so users can see what the field is for at a glance. Use `.input-icon-addon` after the input to place the icon on the right, or before it to place the icon on the left. + + +
+
+ + +
+
+ +### Inline calendar + +Give Litepicker an empty `div` instead of an input, and pass `inlineMode: true`. The calendar then renders directly on the page instead of opening in a popover. Use this when the date is the main thing on the screen, for example a booking or availability page. + + +
+
+ +```js +const picker = new Litepicker({ + element: document.getElementById('datepicker-inline'), + inlineMode: true, +}); +``` + +## JavaScript + +### Custom navigation icons + +Litepicker's default previous/next month buttons are plain arrows. Tabler replaces them with [Tabler Icons](/icons) chevrons through the `buttonText` option, which accepts HTML for each button. + +```js +const picker = new Litepicker({ + element: document.getElementById('datepicker-basic'), + buttonText: { + previousMonth: '', + nextMonth: '', + }, +}); +``` + +Litepicker uses `buttonText` as the buttons' `innerHTML`, and the icon SVGs are `aria-hidden`, so the generated buttons have no accessible name on their own. Litepicker also re-renders these buttons on every open and every month change, so re-apply the labels on each `render` event instead of once at init: + +```js +picker.on('render', () => { + picker.ui?.querySelector('.button-previous-month')?.setAttribute('aria-label', 'Previous month'); + picker.ui?.querySelector('.button-next-month')?.setAttribute('aria-label', 'Next month'); +}); +``` + +### Common options + +These are the options you will need most often. Litepicker has more, and they are listed in its [documentation](https://litepicker.com/#option). + +| Option | What it does | +| --- | --- | +| `element` | The input or element Litepicker attaches to. | +| `inlineMode` | Renders the calendar on the page instead of in a popover. | +| `singleMode` | `true` picks one date; `false` picks a date range. | +| `format` | Format of the date shown in the field, for example `YYYY-MM-DD`. | +| `minDate` / `maxDate` | Limits the range of selectable dates. | +| `lockDays` | List of dates users cannot pick. | +| `numberOfColumns` / `numberOfMonths` | Shows more than one month at a time. | +| `buttonText` | HTML for the previous/next month and other buttons. | + +## Accessibility + +- Always add a `