Label

A label that follows its control, dimming when it's disabled and marking it required or optional on its own.

Team

Send me product updates

import { Checkbox } from "@/components/ui/checkbox"
import { Input } from "@/components/ui/input"
import { Label } from "@/components/ui/label"

export function LabelDemo() {
  return (
    <div className="flex w-full max-w-sm flex-col gap-6">
      <div className="flex flex-col gap-2">
        <Label htmlFor="label-demo-email" indicator="required">
          Email
        </Label>
        <Input
          id="label-demo-email"
          type="email"
          autoComplete="email"
          required
        />
      </div>
      <div className="flex flex-col gap-2">
        <Label htmlFor="label-demo-team" indicator="required">
          Team
        </Label>
        <Input id="label-demo-team" defaultValue="Design systems" disabled />
      </div>
      <Label>
        <Checkbox defaultChecked />
        Send me product updates
      </Label>
    </div>
  )
}

Installation

pnpm dlx shadcn@latest add https://hextaui.com/r/label.json

Adds the component, the HextaUI theme tokens and any HextaUI components it depends on.

Add the theme tokens to your global CSS, if you haven’t yet.
2
Install the dependencies.
```
pnpm add @base-ui/react cn
```

Copy and paste the following code into your project.

components/ui/label.tsx

"use client"

import * as React from "react"
import { mergeProps } from "@base-ui/react/merge-props"
import { useRender } from "@base-ui/react/use-render"
import { cn } from "cn"

type LabelIndicator = "required" | "optional"

type ControlState = {
  disabled: boolean
  required: boolean
  invalid: boolean
  readOnly: boolean
}

const idleState: ControlState = {
  disabled: false,
  required: false,
  invalid: false,
  readOnly: false,
}

const controlSelector =
  'input:not([type="hidden"]), textarea, select, button, meter, output, progress, [role="checkbox"], [role="switch"], [role="radio"], [role="combobox"], [role="slider"]'

function findControl(label: HTMLLabelElement) {
  if (label.htmlFor) {
    return document.getElementById(label.htmlFor)
  }
  return label.querySelector<HTMLElement>(controlSelector)
}

function readState(control: HTMLElement | null): ControlState {
  if (!control) {
    return idleState
  }
  return {
    disabled:
      control.matches(":disabled") ||
      control.hasAttribute("data-disabled") ||
      control.getAttribute("aria-disabled") === "true",
    required:
      control.matches(":required") ||
      control.getAttribute("aria-required") === "true" ||
      control.hasAttribute("data-required"),
    invalid:
      control.getAttribute("aria-invalid") === "true" ||
      control.hasAttribute("data-invalid") ||
      control.matches(":user-invalid"),
    readOnly:
      control.matches(":read-only:is(input, textarea)") ||
      control.getAttribute("aria-readonly") === "true" ||
      control.hasAttribute("data-readonly"),
  }
}

function sameState(a: ControlState, b: ControlState) {
  return (
    a.disabled === b.disabled &&
    a.required === b.required &&
    a.invalid === b.invalid &&
    a.readOnly === b.readOnly
  )
}

function useControlState(
  labelRef: React.RefObject<HTMLLabelElement | null>,
  htmlFor: string | undefined
) {
  const [state, setState] = React.useState(idleState)

  React.useEffect(() => {
    const label = labelRef.current
    if (!label) {
      return
    }

    let control: HTMLElement | null = null
    let frame = 0
    const attributes = new MutationObserver(() => sync())
    const children = new MutationObserver(() => connect())

    const sync = () => {
      const next = readState(control)
      setState((previous) => (sameState(previous, next) ? previous : next))
    }

    const connect = () => {
      const found = findControl(label)
      if (found === control) {
        return
      }
      control = found
      attributes.disconnect()
      if (control) {
        attributes.observe(control, {
          attributes: true,
          attributeFilter: [
            "disabled",
            "required",
            "readonly",
            "aria-disabled",
            "aria-required",
            "aria-invalid",
            "aria-readonly",
            "data-disabled",
            "data-required",
            "data-invalid",
            "data-readonly",
          ],
        })
      }
      sync()
    }

    const onFieldEvent = (event: Event) => {
      if (control && event.target === control) {
        sync()
      }
    }

    connect()
    if (!control) {
      frame = requestAnimationFrame(connect)
    }
    if (!htmlFor) {
      children.observe(label, { childList: true, subtree: true })
    }
    window.addEventListener("input", onFieldEvent)
    window.addEventListener("change", onFieldEvent)
    window.addEventListener("focusout", onFieldEvent)
    window.addEventListener("invalid", onFieldEvent, true)

    return () => {
      cancelAnimationFrame(frame)
      attributes.disconnect()
      children.disconnect()
      window.removeEventListener("input", onFieldEvent)
      window.removeEventListener("change", onFieldEvent)
      window.removeEventListener("focusout", onFieldEvent)
      window.removeEventListener("invalid", onFieldEvent, true)
    }
  }, [labelRef, htmlFor])

  return state
}

type LabelProps = useRender.ComponentProps<"label"> & {
  indicator?: LabelIndicator
  optionalText?: React.ReactNode
}

function Label({
  className,
  indicator,
  optionalText = "Optional",
  render,
  children,
  htmlFor,
  onMouseDown,
  ref,
  ...props
}: LabelProps) {
  const labelRef = React.useRef<HTMLLabelElement | null>(null)
  const state = useControlState(labelRef, htmlFor)
  const setRef = React.useCallback(
    (node: HTMLLabelElement | null) => {
      labelRef.current = node
      if (typeof ref === "function") {
        return ref(node)
      }
      if (ref) {
        ref.current = node
      }
      return undefined
    },
    [ref]
  )

  const mark =
    indicator === "required" && state.required ? (
      <span
        aria-hidden="true"
        data-slot="label-indicator"
        data-indicator="required"
        className="-ms-1.5 shrink-0 self-start font-normal whitespace-nowrap text-muted-foreground"
      >
        *
      </span>
    ) : indicator === "optional" && !state.required ? (
      <span
        aria-hidden="true"
        data-slot="label-indicator"
        data-indicator="optional"
        className="shrink-0 self-start font-normal whitespace-nowrap text-muted-foreground"
      >
        {optionalText}
      </span>
    ) : null

  return useRender({
    defaultTagName: "label",
    render,
    ref: setRef,
    props: mergeProps<"label">(
      {
        htmlFor,
        className: cn(
          "inline-flex w-fit max-w-full min-w-0 items-center gap-2 text-sm leading-snug font-medium text-pretty wrap-anywhere text-foreground select-none data-disabled:cursor-not-allowed data-disabled:opacity-50 [&>svg]:size-4 [&>svg]:shrink-0 [&>svg]:text-muted-foreground",
          className
        ),
        onMouseDown: (event) => {
          onMouseDown?.(event)
          const target = event.target as Element
          if (
            !event.defaultPrevented &&
            event.detail > 1 &&
            !target.closest(controlSelector)
          ) {
            event.preventDefault()
          }
        },
        children: (
          <>
            {children}
            {mark}
          </>
        ),
      },
      props,
      {
        "data-slot": "label",
        ...(state.disabled ? { "data-disabled": "" } : {}),
        ...(state.required ? { "data-required": "" } : {}),
        ...(state.invalid ? { "data-invalid": "" } : {}),
        ...(state.readOnly ? { "data-readonly": "" } : {}),
      } as React.ComponentProps<"label">
    ),
  })
}

export { Label }
export type { LabelIndicator, LabelProps }

Update the import paths to match your project setup.

Usage

import { Label } from "@/components/ui/label"

<Label htmlFor="email">Email</Label>
<Input id="email" type="email" />

Point htmlFor at a control's id, or wrap the control. Either way the label finds it and follows its state. Inside a <Field />, use <FieldLabel />, which wires up the id for you.

Examples

Follows its control

The label dims and shows a not-allowed cursor while its control is disabled, and exposes data-required, data-invalid and data-readonly for your own styles. It keeps up when the control changes.

Custom domain

"use client"

import * as React from "react"

import { Button } from "@/components/ui/button"
import { Input } from "@/components/ui/input"
import { Label } from "@/components/ui/label"

export function LabelStates() {
  const [locked, setLocked] = React.useState(true)

  return (
    <div className="flex w-full max-w-sm flex-col gap-3">
      <div className="flex flex-col gap-2">
        <Label htmlFor="label-states-domain">Custom domain</Label>
        <Input
          id="label-states-domain"
          defaultValue="docs.example.com"
          disabled={locked}
        />
      </div>
      <Button
        variant="outline"
        size="sm"
        className="self-start"
        onClick={() => setLocked(!locked)}
      >
        {locked ? "Unlock" : "Lock"}
      </Button>
    </div>
  )
}

indicator="optional" tags controls without required, and indicator="required" adds an asterisk to controls with it. The mark is hidden from screen readers, which already announce required fields.

Full name

Company

Card number

import { Input } from "@/components/ui/input"
import { Label } from "@/components/ui/label"

export function LabelIndicator() {
  return (
    <div className="grid w-full max-w-sm gap-6">
      <div className="flex flex-col gap-2">
        <Label htmlFor="label-indicator-name" indicator="optional">
          Full name
        </Label>
        <Input id="label-indicator-name" autoComplete="name" required />
      </div>
      <div className="flex flex-col gap-2">
        <Label htmlFor="label-indicator-company" indicator="optional">
          Company
        </Label>
        <Input id="label-indicator-company" autoComplete="organization" />
      </div>
      <div className="flex flex-col gap-2">
        <Label htmlFor="label-indicator-card" indicator="required">
          Card number
        </Label>
        <Input id="label-indicator-card" inputMode="numeric" required />
      </div>
    </div>
  )
}

Checkbox

Wrap a checkbox so the whole label toggles it, or place the label beside it with htmlFor. A disabled checkbox dims its label either way.

Email me when someone repliesWeekly digest (coming soon)

Accept the terms

import { Checkbox } from "@/components/ui/checkbox"
import { Label } from "@/components/ui/label"

export function LabelCheckbox() {
  return (
    <div className="flex flex-col gap-4">
      <Label>
        <Checkbox defaultChecked />
        Email me when someone replies
      </Label>
      <Label>
        <Checkbox disabled />
        Weekly digest (coming soon)
      </Label>
      <div className="flex items-center gap-2">
        <Checkbox id="label-checkbox-terms" />
        <Label htmlFor="label-checkbox-terms">Accept the terms</Label>
      </div>
    </div>
  )
}

Icon

Icons inside a label are sized and muted to sit next to the text.

API key

import { IconLock } from "@tabler/icons-react"

import { Input } from "@/components/ui/input"
import { Label } from "@/components/ui/label"

export function LabelIcon() {
  return (
    <div className="flex w-full max-w-sm flex-col gap-2">
      <Label htmlFor="label-icon-key">
        <IconLock aria-hidden="true" />
        API key
      </Label>
      <Input id="label-icon-key" defaultValue="sk_live_51H…" readOnly />
    </div>
  )
}

Long content

Long labels wrap, and unbroken strings break instead of widening the layout.

Where should we send invoices for the international subsidiary

billing-notifications@an-extremely-long-company-domain.example.com

import { Checkbox } from "@/components/ui/checkbox"
import { Input } from "@/components/ui/input"
import { Label } from "@/components/ui/label"

export function LabelLongContent() {
  return (
    <div className="flex w-64 max-w-full flex-col gap-6">
      <div className="flex flex-col gap-2">
        <Label htmlFor="label-long" indicator="optional">
          Where should we send invoices for the international subsidiary
        </Label>
        <Input id="label-long" />
      </div>
      <Label>
        <Checkbox />
        billing-notifications@an-extremely-long-company-domain.example.com
      </Label>
    </div>
  )
}

Right to left

Gaps and the indicator follow the reading direction.

الاسم

تذكرني

import { Checkbox } from "@/components/ui/checkbox"
import { Input } from "@/components/ui/input"
import { Label } from "@/components/ui/label"

export function LabelRtl() {
  return (
    <div dir="rtl" className="flex w-full max-w-sm flex-col gap-6">
      <div className="flex flex-col gap-2">
        <Label
          htmlFor="label-rtl-name"
          indicator="optional"
          optionalText="اختياري"
        >
          الاسم
        </Label>
        <Input id="label-rtl-name" />
      </div>
      <Label>
        <Checkbox defaultChecked />
        تذكرني
      </Label>
    </div>
  )
}

Accessibility

Clicking the label focuses or toggles its control, so it's a bigger target than the control alone.
Double-clicking the label text doesn't select it. Double-clicks on a control inside the label work as usual.
Every control needs a name. When there's no visible label, use aria-label on the control instead.

API reference

Renders a <label> and accepts its attributes.

Label

Prop	Type	Default
`htmlFor`The id of the control. Leave it out when the label wraps the control.	`string`	`–`
`indicator`Mark the label from the control's required state. Off by default.	`"required" \| "optional"`	`–`
`optionalText`	`ReactNode`	`"Optional"`
`render`	`ReactElement \| (props, state) => ReactElement`	`<label>`

Attribute	Description
`data-slot="label"`	Target labels in CSS.
`data-disabled`	Present while the control is disabled.
`data-required`	Present while the control is required.
`data-invalid`	Present while the control is invalid, after the user has interacted or when aria-invalid is set.
`data-readonly`	Present while the control is read-only.
`data-slot="label-indicator"`	The required or optional mark.