{"slug":"label","name":"Label","packageName":"@liquidify/react","category":"presentational","maturity":"experimental","summary":"Pair a leading icon with a title so the two read as one unit — the \"gear + Settings\" row in a sidebar, the \"trash + Delete\" row in a context menu, the \"star + Favorites\" tab.","importPath":"@liquidify/react/label","sourcePath":"packages/@liquidify/react/src/components/label/label.tsx","specPath":"packages/@liquidify/react/src/components/label/spec.md","docsPath":"../liquidify-page/content/component-source/label.md","documentationStatus":"draft","storyIds":["presentational-label--default"],"additionalExports":["ControlProps","LabelVariant"],"anatomy":[{"name":".lq-label-title (variant=\"titleAndIcon\" / \"titleOnly\")","description":".lq-label-title (variant=\"titleAndIcon\" / \"titleOnly\") — visible,"},{"name":".lq-label-visually-hidden (variant=\"iconOnly\")","description":".lq-label-visually-hidden (variant=\"iconOnly\") — clipped to a 2×2pt"}],"props":[{"name":"as","type":"TextElement | undefined","required":false,"description":"The HTML element the title's {@link Text} renders as, so the type carries the right semantics (SwiftUI has no analogue — a web affordance). Only applies when the title is wrapped (a `string | number`).","defaultValue":"`\"span\"`","declaredIn":"packages/@liquidify/react/src/components/label/label.tsx"},{"name":"className","type":"string | undefined","required":false,"description":"Optional additional CSS class merged into the glass surface class. The supported per-instance customisation seam: override any `--lq-*` custom property from this class's CSS — the token cascade the engine reads (ADR-0004). No raw inline style is involved, so this stays ADR-0003 clean.","declaredIn":"packages/@liquidify/react/src/liquid-component-props.ts"},{"name":"icon","type":"ReactNode","required":false,"description":"The leading icon (SwiftUI `systemImage:` / `icon:`). Decorative (`aria-hidden`) — the title carries the accessible name. Omit for a title-only label; ignored when {@link LabelProps.variant} is `\"titleOnly\"`.","declaredIn":"packages/@liquidify/react/src/components/label/label.tsx"},{"name":"labelProps","type":"SharedLabelProps | undefined","required":false,"description":"Per-instance typography override for the title `Text` (ADR-0028, charter §2 — the catalog-wide typography seam name), spread last so an explicit consumer value wins over the component default.","defaultValue":"`undefined`","declaredIn":"packages/@liquidify/react/src/components/label/label.tsx"},{"name":"ref","type":"Ref<HTMLSpanElement> | undefined","required":false,"description":"Forwarded ref to the rendered element — the component's native root (or the merged child element on a component that opts into {@link SlottableProps}). Generic over `E` (charter `docs/api-conventions.md` §4 rule 1, default `HTMLElement`) so a component with a polymorphic root (Link's navigation / action mode union, Text's `as`) can instantiate the concrete element per variant instead of leaving every consumer with a widened `Ref<HTMLElement>`. A component that does not narrow simply inherits the `HTMLElement` default — source-compatible with every pre-existing non-generic `extends ControlProps`.","declaredIn":"packages/@liquidify/react/src/liquid-component-props.ts"},{"name":"title","type":"ReactNode","required":true,"description":"The title (SwiftUI `_:` / `title:`) — the accessible name, always present. A `string | number` renders through the `TextLabel` guard into an internal `Text`; any other `ReactNode` passes through unwrapped so the caller keeps ownership of its typography.","declaredIn":"packages/@liquidify/react/src/components/label/label.tsx"},{"name":"variant","type":"LabelVariant | undefined","required":false,"description":"Which of the pairing to render (SwiftUI `.labelStyle(_:)`). `\"iconOnly\"` keeps the title in the DOM (visually hidden) so the accessible name survives.","defaultValue":"`\"titleAndIcon\"`","declaredIn":"packages/@liquidify/react/src/components/label/label.tsx"}],"swiftUIMap":[{"swiftUI":"`init(_ titleKey:, systemImage name:)` / `init<S>(_ title:, systemImage name:)`","react":"`<Label title=\"Settings\" icon={<Icon name=\"gear\" />} />`","notes":"The two SF-Symbol convenience inits collapse to one `title` + one `icon` prop; `icon` accepts any `ReactNode` (not a name string) so the caller supplies a rendered `Icon`/custom glyph rather than a symbol-name lookup.","relationship":"renamed"},{"swiftUI":"`init(_ titleKey:, image name:)` / `init<S>(_ title:, image name:)`","react":"same `<Label title icon />` shape","notes":"Asset-catalog-image and SF-Symbol convenience inits are not distinguished in React — both are \"pass a rendered icon node,\" so they map onto the same `icon` prop rather than two.","relationship":"direct"},{"swiftUI":"`init(@ViewBuilder title:, @ViewBuilder icon:)`","react":"`title`/`icon` accept arbitrary `ReactNode`","notes":"The fully-custom ViewBuilder init is not a separate React overload — `title: ReactNode` and `icon?: ReactNode` already accept any element, covering this case without a second prop shape.","relationship":"direct"},{"swiftUI":"`init(_ configuration: LabelStyleConfiguration)`","react":"— (Out of scope)","notes":"Style-plumbing internal, not app-facing; no React equivalent is exposed.","relationship":"direct"},{"swiftUI":"`.labelStyle(_:)` + `.automatic`/`.titleAndIcon`/`.iconOnly`/`.titleOnly`","react":"`variant?: \"titleAndIcon\" | \"iconOnly\" | \"titleOnly\"`","notes":"A style *modifier* becomes one `variant` prop, never a fan of booleans (`showIcon`/`showTitle`). `.automatic` collapses into `\"titleAndIcon\"` (the default) since every reference use of `.automatic` resolves to showing both.","relationship":"renamed"},{"swiftUI":"*(no title-only single-argument `Label(_:)` exists in SwiftUI)*","react":"`variant=\"titleOnly\"` (title always required as a separate prop)","notes":"SwiftUI has no bare-title initialiser (`tmp/refs/label.md` §Initialisers note); this component preserves that shape — `title` is a required prop regardless of `variant`, and `\"titleOnly\"` is a *presentation* choice, not a different constructor.","relationship":"direct"},{"swiftUI":"*(no analogue — web-only)*","react":"`as?: TextElement`, default `\"span\"`","notes":"The HTML element the title's `Text` renders as (`span`/`div`/`p`/`b`/`strong`/`i`/`em`/`pre`/`code`/`sup`/`sub`) — a semantic-HTML affordance SwiftUI has no need for (it has no DOM). Applies only when the title is a `string`/`number` wrapped by `TextLabel`.","relationship":"web-only"},{"swiftUI":"*(no analogue — web-only, ADR-0028/charter §2)*","react":"`labelProps?: LabelProps[\"labelProps\"]` (`Pick<TextProps, \"variant\" | \"weight\" | \"color\" | \"tint\" | \"tracking\" | \"transform\" | \"italic\" | \"lineHeight\" | \"wrap\">` — the shared `shared/text-label` Text seam)","notes":"Per-instance typography override for the title, spread last so an explicit value wins over the component default (`variant=\"body\"`, `color=\"primary\"`). Named `labelProps` (not `titleProps`) to match the catalog-wide seam name (charter §2); no public `LabelTextProps` alias — the shape is reachable via `LabelProps[\"labelProps\"]`.","relationship":"web-only"}],"tokens":["--lq-color-label-","--lq-color-label-primary-dark","--lq-color-label-primary-light","--lq-font-size-body","--lq-glass-","--lq-icon-","--lq-label-gap","--lq-label-pad","--lq-line-height-body","--lq-space-2","--lq-space-8"],"keyboard":[],"variants":["iconOnly","titleAndIcon","titleOnly"],"variantPages":[]}