import { FrontmatterFields, type FieldSpec } from "capsomer/react/frontmatter-fields";
const fields: FieldSpec[] = [
{ key: "title", label: "Title" },
{ key: "description", label: "Description", box: "text" },
{ key: "tags", label: "Tags", box: "list" },
{ key: "banner", label: "Draft banner", box: "flag", flag: { on: "Draft", off: null } },
];
<FrontmatterFields source={source} onChange={setSource} fields={fields} extra="text" legend="Post details">
{/* the app's own controls, in the grid after the boxes */}
</FrontmatterFields>;
Examples
With the app's labels, help and flag word
<div data-mount="specs"></div>
Read-only, empty boxes hidden
<div data-mount="readonly"></div>
Keys the app does not type: the text alone, open
<div data-mount="text"></div>
A file with no frontmatter
<div data-mount="none"></div>
API reference
FrontmatterFields
Prop
Type
Required
Does
source
string
Yes
The whole file: frontmatter fences, frontmatter and body.
onChange
(next: string) => void
The whole file again, with the change made. Left out, every box is read-only.
readOnly
boolean
fields
readonly FieldSpec[]
What the app knows about its keys: labels, boxes, help, flag words, order.
extra
"fields" | "text"
A key with no spec: a box of its own ("fields", the default) or the raw text only ("text").
legend
ReactNode
hideEmpty
boolean
Hide boxes whose key is absent and empty; on by default when read-only.
raw
boolean
The raw text disclosure: shown by default.
rawSummary
ReactNode
empty
ReactNode
Shown in place of the fields when the file has no frontmatter.
children
ReactNode
After the boxes: the app's own controls for this item.
Functions
Function
Signature
Does
useTyped
(stored: string): TypedBox
shapeOf
(lines: readonly string[]): BoxKind | null
The box a block's shape allows, or null when no box can say it. A block list or flow list whose items hold a comma is "lines", since "a, b" could not give them back.
labelOf
(key: string): string
"pov" reads as "POV", "first_line" as "First line": the key itself is in the raw text.
A scalar as YAML reads it back as the same string: quoted only when it would otherwise be read as syntax, a number, a boolean or null. An ISO date stays bare, as sites write it.
The frontmatter with one box's value set. A box that already shows the value leaves the text as it was; an emptied box removes its key (or, with keep, writes it empty); a key the frontmatter lacks is added at the end. The blank lines that followed the block are kept.
Each box the frontmatter gets: the app's specs first, in their order, then the keys it has no spec for, in file order. A key whose shape no box can say is raw only, whatever its spec says.
CSS variables
Variable
Default
--fields-gap
var(--gap)
--fields-min
14rem
Parts and data attributes
Class
Is
.cap-fm
the root
.cap-fm-field
a part
.cap-fm-grid
a part
.cap-fm-legend
a part
.cap-fm-raw-text
a part
Attribute
Values
data-wide
present or absent
State
Read from
:empty
the platform
Accessibility
Key
Does
Tab, Shift+Tab
Moves between the boxes, then the "Edit as text" summary and the raw text
Space (checkbox)
Turns a flag on or off
Enter or Space (summary)
Opens or closes the raw text
The boxes are in a fieldset named by its legend; each box is a Field, its label above it and its help as its description. A flag is a .cap-check checkbox, its help as its description.
The raw text is a labeled textarea ("The frontmatter as text"), described by the line that names the keys only it holds.
Read-only boxes are readonly, so they keep focus and can be read and copied; a read-only flag is disabled.
Hit areas are Field's and the disclosure's, at least --target.
Forced colors: the fieldset's edge is a border, so it stays.