4e:I[314491,["/_next/static/immutable/chunks/3arlv5bvukoo2.js","/_next/static/immutable/chunks/39v64hmfyo-sr.js","/_next/static/immutable/chunks/2nvof3-29tvc3.js","/_next/static/immutable/chunks/3tjobt77z_9dj.js","/_next/static/immutable/chunks/04j_o97cgxn2x.js","/_next/static/immutable/chunks/3upr08c9vtj8w.js","/_next/static/immutable/chunks/1ww0328si-u8x.js","/_next/static/immutable/chunks/11mfl5ymqld9-.js","/_next/static/immutable/chunks/2xxcqy6ppds3l.js","/_next/static/immutable/chunks/3j06ow7w40nxu.js","/_next/static/immutable/chunks/31nn7jwsjvqii.js","/_next/static/immutable/chunks/43_s7jweyypoh.js","/_next/static/immutable/chunks/0p6vao205o1jc.js","/_next/static/immutable/chunks/1_kyvgkyokw92.js","/_next/static/immutable/chunks/1lo-zn37dolb5.js","/_next/static/immutable/chunks/1v8k6yxw1rg0u.js"],"FilesView"] 4f:T1a7b,--- title: Date description: Inline void date elements with canonical and raw date storage. docs: - route: /docs/components/date-node title: Date Element - route: https://pro.platejs.org/docs/components/date-node title: Plus --- Date adds inline void elements that display a date label inside text. Canonical dates are stored as `YYYY-MM-DD`; non-normalizable input is kept as `rawDate`. This page covers kit setup, insertion, value shape, picker behavior, Markdown serialization, and the small query API. ## Features - Inline void `date` element. - Bound `editor.tf.insert.date` transform. - Direct `insertDate(editor, options)` helper. - Canonical `date` storage with `rawDate` fallback. - Calendar editing in the registry UI. - Static renderer for read-only output. - Markdown round-trip through `` and child-text date tags. ## Fast Path ### Add The Kit `DateKit` installs `DatePlugin` with the registry `DateElement`. ```tsx import { createPlateEditor } from 'platejs/react'; import { DateKit } from '@/components/editor/plugins/date-kit'; export const editor = createPlateEditor({ plugins: DateKit, }); ``` ### Render The Element `date-node` owns the inline wrapper, display label, popover, calendar picker, and static element. ### Add An Insert Action The registry insert toolbar maps `KEYS.date` to `insertDate(editor, { select: true })`. ```tsx title="components/editor/transforms.ts" import { insertDate } from '@platejs/date'; import { KEYS } from 'platejs'; export const insertInlineMap = { [KEYS.date]: (editor) => insertDate(editor, { select: true }), }; ``` ## Ownership | Layer | Owner | What It Does | |-------|-------|--------------| | `@platejs/date` | Package | Exports `BaseDatePlugin`, `insertDate`, date value helpers, and `isPointNextToNode`. | | `@platejs/date/react` | Package | Exports `DatePlugin`. | | `date-kit` | Registry | Adds `DatePlugin.withComponent(DateElement)`. | | `date-base-kit` | Registry | Adds `BaseDatePlugin.withComponent(DateElementStatic)`. | | `date-node` | Registry UI | Renders the editable popover/calendar element and static element. | | `@platejs/markdown` | Package | Converts date MDX tags to canonical `date` or fallback `rawDate` values. | `BaseDatePlugin` is inline and void. The text child exists only to satisfy Slate's element shape. ## Manual Setup ### Install Package ```bash npm install @platejs/date ``` ### Add The Plugin Use the React plugin when the editor renders the calendar popover. ```tsx import { DatePlugin } from '@platejs/date/react'; import { createPlateEditor } from 'platejs/react'; import { DateElement } from '@/components/ui/date-node'; export const editor = createPlateEditor({ plugins: [DatePlugin.withComponent(DateElement)], }); ``` ### Add Static Rendering Use the base kit when rendering read-only output with `platejs/static`. ### Insert A Date `DatePlugin` binds `insertDate` to `editor.tf.insert.date`. ```tsx editor.tf.insert.date({ date: '2026-03-23', select: true, }); ``` Use the package helper directly when you are outside plugin-bound transform access. ```tsx import { insertDate } from '@platejs/date'; insertDate(editor, { date: '2026-03-23', select: true, }); ``` ## Value Shape Canonical date values live in `date`. Invalid or intentionally loose date text lives in `rawDate`. ```tsx const value = [ { children: [ { text: 'Due ' }, { children: [{ text: '' }], date: '2026-03-23', type: 'date', }, { text: '.' }, ], type: 'p', }, ]; ``` | Field | Type | Notes | |-------|------|-------| | `type` | `'date'` | Plugin key and node type from `KEYS.date`. | | `children` | `[{ text: '' }]` | Required Slate child for the inline void element. | | `date` | `string` | Canonical `YYYY-MM-DD` value. | | `rawDate` | `string` | Fallback for non-normalizable input. | ## Date Normalization `normalizeDateValue` decides which field is written. | Input | Stored Value | |-------|--------------| | `Date` object | `date: formatDateValue(value)` when the object is valid. | | `YYYY-MM-DD` | `date` when the calendar date is valid. | | Invalid canonical string | `rawDate`. | | `Mon Mar 23 2026` | `date: '2026-03-23'` when JavaScript can parse it. | | Blank string | no date fields. | | Other text | `rawDate`. | `getDateDisplayLabel` returns `Today`, `Yesterday`, `Tomorrow`, a localized long date, or the raw fallback string. ## Picker Behavior The registry element is display-only while read-only. In editable mode, clicking the inline label opens a calendar popover. | State | Behavior | |-------|----------| | `date` exists | The trigger shows `getDateDisplayLabel(element)`. | | `rawDate` exists | The trigger shows the raw string. | | no date fields | The trigger shows `Pick a date`. | | calendar selection | The node is set to `{ date: formatDateValue(date), rawDate: undefined }`. | The registry element uses `contentEditable={false}` on the inline wrapper, so users edit the date through the calendar instead of typing inside the void node. ## Markdown Canonical values serialize as a self-closing date tag with a `value` attribute. ```mdx Date: ``` Raw fallback values serialize as child text. ```mdx Date: sometime next week ``` The deserializer also accepts child text such as `Mon Mar 23 2026` and normalizes it to `date: '2026-03-23'` when the date is safe to parse. ## API Reference | API | Package | Use | |-----|---------|-----| | `BaseDatePlugin` | `@platejs/date` | Headless inline void date plugin. | | `DatePlugin` | `@platejs/date/react` | React date plugin. | | `insertDate(editor, options)` | `@platejs/date` | Inserts a date element plus a trailing text space. | | `editor.tf.insert.date(options)` | plugin-bound transform | Bound transform registered by `BaseDatePlugin`. | | `normalizeDateValue(value)` | `@platejs/date` | Returns `{ date }`, `{ rawDate }`, or an empty object. | | `formatDateValue(date)` | `@platejs/date` | Formats a `Date` object as `YYYY-MM-DD`. | | `parseCanonicalDateValue(value)` | `@platejs/date` | Parses only valid canonical date strings. | | `getDateDisplayLabel(options)` | `@platejs/date` | Builds the visible date label. | | `isPointNextToNode(editor, options)` | `@platejs/date` | Checks whether a point is adjacent to a node type. Throws when neither `options.at` nor editor selection exists. | | `TDateElement` | `platejs` | Element shape with optional `date` and `rawDate`. | 4d:["$","div",null,{"className":"mt-3 flex min-h-0 min-w-0 flex-1 flex-col gap-3","children":[null,["$","$L4e",null,{"files":[{"path":"../../content/docs/(plugins)/(elements)/date.mdx","content":"$4f","type":"registry:file","target":"content/docs/plate/(plugins)/(elements)/date.mdx"}],"className":"h-[70svh] min-h-80"}]]}]