Field and section labels with leading and trailing slots, required and optional marks, subtext, control inset alignment, and typography chrome.
Also known as: field label, form label, accessible label, section label
Install with the CLI, or copy the component source into your project.
Add label (npm)
1npx --yes -p @default-file/ui df-ui add label
Standalone label.
Required mark as a red asterisk.
Required mark as red (required) text. Override with requiredColor.
Optional mark as muted catalogue text such as (optional).
Optional mark as a muted asterisk.
Supporting line under the title.
Trailing character count paired with an input.
Use Badge in the trailing slot to highlight a field.
leading is a ReactNode slot before the title. Prefer FeaturedIcon plain at size md with glyphShadow off for a bare mark that matches the leading size token. You can pass any node.
Align the label to the control outer edge. Default.
Align the label to the default control content start via --df-control-content-inset-inline.
Same content inset as a leading icon. First content starts at the shared control inset.
Set insetAlign custom with insetSize when the paired control uses a non-default content inset.
Field and section label with leading and trailing slots, required and optional marks, subtext, control inset alignment, and typography chrome. Use as="label" with htmlFor for form controls. Use as="div" for section titles that share the same chrome.
Root element, title content, and slots.
| Prop | Type | Default | Notes |
|---|---|---|---|
| as | "label" | "div" | "label" | Root element. "label" associates with a control via htmlFor. "div" is for section titles such as SidebarGroupLabel. |
| htmlFor | string | - | Id of the labeled control. Applies when as is label. |
| children | ReactNode | - | Primary title content. |
| leading | ReactNode | - | Slot before the title text. Prefer FeaturedIcon plain at size md with glyphShadow off for a bare mark that matches the leading size token. Plain SVG icons still fit that token. |
| trailing | ReactNode | - | End-aligned slot on the title row. Pass Badge, a character count, an icon, or a control such as SidebarGroupAction. |
| subtext | ReactNode | - | Secondary supporting line under the title row. |
| className | string | - | Additional classes on the root. |
| style | CSSProperties | - | Inline styles on the root. Can set --label-required and --df-label-* chrome vars. |
Horizontal inset relative to a paired control. content uses --df-control-content-inset-inline, the same default as Input and Select content start.
| Prop | Type | Default | Notes |
|---|---|---|---|
| insetAlign | "left" | "content" | "custom" | "left" | left aligns to the control outer edge. content aligns to the default control content start (text, or a leading icon at that inset). custom uses insetSize. |
| insetSize | string | - | Required for a non-zero custom inset when insetAlign is custom. Prefer spacing tokens such as calc(5 * var(--spacing-unit)). Sets --df-label-inset-custom. |
Decorative required and optional indicators after the title.
| Prop | Type | Default | Notes |
|---|---|---|---|
| required | boolean | false | Shows a decorative required mark after the title. Wins over optional when both are set. |
| requiredVariant | "asterisk" | "text" | "asterisk" | Required mark style. "asterisk" renders the catalogue asterisk string as-is. "text" renders the catalogue required string as-is. Color uses --label-required. |
| requiredColor | string | - | Required mark color. Prefer tokens such as var(--destructive). Sets --label-required. |
| optional | boolean | false | Shows a decorative optional mark after the title. Ignored when required is true. |
| optionalVariant | "asterisk" | "text" | "text" | Optional mark style. "text" renders the catalogue optional string as-is. "asterisk" renders the catalogue asterisk string as-is. |
Title color and type. Prefer kit tokens for values.
| Prop | Type | Default | Notes |
|---|---|---|---|
| color | string | - | Title color. Prefer tokens such as var(--muted-foreground). Sets --df-label-color. |
| fontFamily | string | - | Title font family. Sets --df-label-font. |
| fontSize | string | - | Title font size. Sets --df-label-size. |
| fontWeight | string | - | Title font weight. Sets --df-label-weight. |
DOM structure markers for styling and tests. These are not component props. data-df="label": Root element. data-inset is left, content, or custom. data-df="label-row": Title row with the title group and trailing slot. data-df="label-title": Title group: leading slot, title text, and required or optional mark. data-df="label-leading": Leading slot before the title text. data-df="label-text": Primary title text. data-df="label-required": Required mark. Uses --label-required. data-variant is asterisk or text. data-df="label-optional": Optional mark. data-variant is asterisk or text. data-df="label-trailing": Trailing slot on the title row for meta, icons, or controls. Uses --df-label-row-gap between multiple trailing children. data-df="label-subtext": Supporting line under the title row.
Theme defaults live on :root. Override these globally or on a local host.
| Token | Type | Default | Notes |
|---|---|---|---|
| --df-label-gap | CSS length | calc(1 * var(--spacing-unit)) | Stack gap between the title row and subtext. |
| --df-label-title-gap | CSS length | calc(1.5 * var(--spacing-unit)) | Gap inside the title group between leading, title text, and marks. |
| --df-label-row-gap | CSS length | calc(2 * var(--spacing-unit)) | Gap on the title row between the title group and trailing slot, and between multiple trailing children. |
| --df-label-leading-size | CSS length | calc(4 * var(--spacing-unit)) | Default width and height for SVG icons in the leading slot. |
| --df-label-trailing-size | CSS length | var(--df-label-leading-size) | Default width and height for direct SVG icons in the trailing slot. Defaults to --df-label-leading-size. |
| --df-label-color | CSS color | var(--foreground) | Title color. Falls back to --foreground. Override with color. |
| --df-label-font | CSS font-family | inherit | Title font family. Override with fontFamily. |
| --df-label-size | CSS length | var(--df-text-sm) | Title font size. Falls back to --df-text-sm. Override with fontSize. |
| --df-label-weight | CSS font-weight | var(--df-font-weight-medium) | Title font weight. Falls back to medium. Override with fontWeight. |
| --df-label-inset | CSS length | 0 | Horizontal inset applied as padding-inline-start. Resolved from insetAlign. |
| --df-label-inset-content | CSS length | var(--df-control-content-inset-inline) | Inset used when insetAlign is content. Defaults to --df-control-content-inset-inline. Input and Select field roots may override this to track their content padding. |
| --df-label-inset-custom | CSS length | 0 | Inset used when insetAlign is custom. Set by insetSize. |
| --df-control-content-inset-inline | CSS length | calc(3 * var(--spacing-unit)) | Shared default control content-start inset. Owned in df-tokens.css. Input, Select, Combobox, and Label content mode consume it. |
| --foreground | CSS color | var(--df-neutral-900) | Default title color when --df-label-color is unset. |
| --muted-foreground | CSS color | var(--df-neutral-500) | Optional mark, subtext, and trailing color. |
| --label-required | CSS color | var(--destructive) | Required mark color. Override globally or via requiredColor. |
| --destructive | CSS color | var(--df-destructive) | Default source for --label-required. |