Label

Label renders text associated with a field or control. It wraps the Radix UI Label primitive and applies labelVariants for typography and disabled-state styling. Pair htmlFor with the control’s id, and match size to Input or other field components when you want consistent density.

Installation

The component is exported from @by/experience-system. Add the package with your package manager:

pnpm add @by/experience-system

In this monorepo, depend on the workspace package (for example via workspace:* or your catalog) so imports resolve to packages/experience-system.

Composition

Use a single Label associated with one control via htmlFor / id, or compose inside field layouts as needed:

Label

Optional grouping with fieldset / legend is an app concern—the primitive itself maps to Radix Label.Root (see Radix Label).

Usage

import { Label } from '@by/experience-system';

Label is a client component ('use client' in the package). Use it inside a Client Component or a dynamic import when using the Next.js App Router.

<Label htmlFor="email">Email</Label>

Examples

Variants

variant controls neutral contrast (subtle vs strong). When variant is strong, emphasis toggles normal vs medium weight. Use className for semantic colors (for example error text on aria-invalid fields).

API Reference

Pieces map to Radix UI Label (Label.Root via radix-ui). Styling and variants come from @by/experience-system (labelVariants in variants.ts). The tables below mirror the upstream Root contract, then list Experience System extensions.

Label

Label renders LabelPrimitive.Root with data-slot="label" and labelVariants({ size, variant, emphasis, className }).

Radix Label.Root supports asChild and forwards native <label> attributes (htmlFor, children, etc.). See the Radix documentation for the complete Root prop list.

Compound typography rules (for example emphasis with strong) live in variants.ts.

Accessibility

• Set htmlFor to the id of the labeled control so clicks activate the control and assistive tech gets a correct name association.
• Disabled and invalid visuals rely on the control (and optional group / peer data attributes); keep aria-invalid and disabled on the control itself.
• For Radix-specific semantics, see Accessibility in the Radix Label docs.

Source in the repo: packages/experience-system/src/components/Label/Label.tsx and variants.ts. Agent-oriented contracts: packages/experience-system/src/components/Label/Label.instructions.md.