Capítulo 35 de 108

Label

Core Idea

Renders an accessible label associated with a form control. Base primitive for standalone label + control pairs; for full form fields, prefer Field/FieldLabel.

Key Concepts

  • htmlFor: associates the label with a control by matching the control's id (standard HTML label association).
  • Field (recommended for forms): for form fields, use the Field component (@/components/ui/field), which includes built-in label, description, and error handling instead of a bare Label.
  • FieldLabel: the Field-aware label used inside Field/FieldSet/FieldGroup compositions; accepts htmlFor and className (e.g. className="font-normal" for checkbox-style fields).
  • RTL: pass dir={dir} to both Label and the paired control; not automatic.
  • Built on Base UI Label (@base-ui/react), install dependency @base-ui/react for manual setup.

Code Examples

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

export function LabelDemo() {
  return (
    <div className="flex gap-2">
      <Checkbox id="terms" />
      <Label htmlFor="terms">Accept terms and conditions</Label>
    </div>
  )
}
  • O que demonstra: associação básica Label/Checkbox via htmlFor/id.
<Field>
  <FieldLabel htmlFor="email">Your email address</FieldLabel>
  <Input id="email" />
</Field>
  • O que demonstra: padrão recomendado para campos de formulário (usar Field+FieldLabel, não Label solto).
<Field orientation="horizontal">
  <Checkbox id="checkout-7j9-same-as-shipping-wgm" defaultChecked />
  <FieldLabel
    htmlFor="checkout-7j9-same-as-shipping-wgm"
    className="font-normal"
  >
    Same as shipping address
  </FieldLabel>
</Field>
  • O que demonstra: Field orientation="horizontal" para pares checkbox+label lado a lado, com label sem peso de fonte extra (font-normal).

Anti-patterns

  • Usar Label solto em formulários complexos: para formulários reais, Field/FieldLabel/FieldDescription/FieldError cobrem descrição e erro automaticamente; Label puro não tem esse suporte.

Key Takeaways

  1. Label é o primitivo de baixo nível; Field/FieldLabel é a composição recomendada para forms.
  2. Associação label-controle sempre via htmlFor + id correspondentes, mesmo dentro de Field.
  3. FieldGroup, FieldSet e FieldLegend combinam com FieldLabel para montar seções de formulário complexas (ex: pagamento, endereço).
  4. RTL exige propagar dir manualmente para Label e o controle associado.

Connects To

  • Field: componente de formulário completo (label + descrição + erro) que substitui Label na maioria dos casos reais.
  • Checkbox: par comum de Label/FieldLabel + Checkbox.
  • Input, Select, Textarea: qualquer controle de formulário usa o mesmo padrão de associação com Label/FieldLabel.
AnteriorComboboxPróximoAccordion