Skip to content

Label

Displays a form label with support for optional indicators and contextual tooltips.

Source Code

import ilha from "ilha";
import { Label } from "areia";

export default ilha.render(() => (
  <div class="flex flex-col gap-3">
    <Label for="default-label-demo" label="Default Label" />
    <Label
      for="optional-label-demo"
      label="Optional Label"
      showOptional
    />
    <Label
      for="tooltip-label-demo"
      label="Label with Tooltip"
      tooltip="Helpful context about this field."
    />
  </div>
));

Import

import { Label } from "areia";

Usage

With Form Components

Some form components include built-in label support. Use their label, required, description, error, or tooltip-related props when you want the standard field layout.

import ilha from "ilha";
import { Input } from "areia";

export default ilha.render(() => (
  <div class="flex w-full max-w-sm flex-col gap-4">
    <Input
      id="middle-name"
      label="Middle name"
      required={false}
      placeholder="Ada"
    />
    <Input
      id="email-updates"
      label="Email"
      labelTooltip="We'll only use this for account notifications."
      placeholder="you@example.com"
      type="email"
    />
  </div>
));

Standalone Label

For custom form layouts, use Label directly and associate it with a control using for or htmlFor.

import ilha from "ilha";
import { Input, Label } from "areia";

export default ilha.render(() => (
  <div class="flex w-full max-w-sm flex-col gap-1.5">
    <Label for="username" label="Username" />
    <Input id="username" placeholder="areia-user" />
  </div>
));

Examples

Optional Field

Use showOptional to display subtle “(optional)” text after the label.

import ilha from "ilha";
import { Input, Label } from "areia";

export default ilha.render(() => (
  <div class="flex w-full max-w-sm flex-col gap-1.5">
    <Label for="nickname" label="Nickname" showOptional />
    <Input id="nickname" placeholder="Ryuz" />
  </div>
));

With Tooltip

Use tooltip to show an info icon with additional context.

import ilha from "ilha";
import { Input, Label } from "areia";

export default ilha.render(() => (
  <div class="flex w-full max-w-sm flex-col gap-1.5">
    <Label
      for="email"
      label="Email"
      tooltip="We'll use this to send you product and account updates."
    />
    <Input
      id="email"
      type="email"
      placeholder="you@example.com"
    />
  </div>
));

Rich Label Content

children accepts markup, so labels can include richer inline formatting when needed.

import ilha from "ilha";
import { Label, Checkbox } from "areia";

export default ilha.render(() => (
  <Checkbox.Item
    value="terms"
    label={
      <Label asContent>
        I agree to the <strong>Terms of Service</strong>
      </Label>
    }
  />
));

Form with Mixed Fields

Use optional indicators only where they help users understand which fields are required.

import ilha from "ilha";
import { Input, Label, Select } from "areia";

export default ilha.render(() => (
  <form class="flex w-full max-w-sm flex-col gap-4">
    <Input
      id="full-name"
      label="Full name"
      required
      placeholder="Ada Lovelace"
    />

    <div class="flex flex-col gap-1.5">
      <Label for="company" label="Company" showOptional />
      <Input id="company" placeholder="Areia Labs" />
    </div>

    <Select
      id="country"
      label="Country"
      placeholder="Select a country"
      items={{
        us: "United States",
        uk: "United Kingdom",
        ca: "Canada",
      }}
    />
  </form>
));

As Content

Use asContent when another component already renders the outer label element and you only need Label’s inline optional/tooltip content.

import ilha from "ilha";
import { Label } from "areia";

export default ilha.render(() => (
  <label class="text-base font-medium text-areia-default">
    <Label
      asContent
      label="Project slug"
      showOptional
      tooltip="Used in generated URLs. You can change it later."
    />
  </label>
));

API Reference

Label

Extends native label attributes.

PropTypeDefaultDescription
childrenunknown-Label content. Takes precedence over label.
labelunknown-Label content used when children is not provided.
showOptionalbooleanfalseShows subtle “(optional)” text after the label.
tooltipunknown-Tooltip content shown through an info icon next to the label.
forstring-The id of the form element this label is associated with.
htmlForstring-Alias for for, useful when matching React-style prop naming.
asContentbooleanfalseRenders only inline label content in a <span> instead of a <label>.
classstring-Additional CSS classes merged with the generated classes.
classNamestring-Alias for class.

Form Component Label Props

Several form components expose label-related props directly. Prefer these when using the component’s built-in field layout.

PropTypeDefaultDescription
labelunknown-Label content. Enables the component’s field wrapper.
requiredboolean-Sets the native required state; false may show optional text on supported fields.
labelTooltipstring-Tooltip or native title content for additional label help.

Design Guidelines

When to Use Optional Indicators

  • Use “(optional)” for optional fields when most fields in a form are required.
  • Be consistent within the same form.
  • Do not rely on visual indicators for validation; use the native required attribute when a field is required.

When to Use Tooltips

  • Provide additional context that does not fit in the label.
  • Explain format requirements or validation rules.
  • Keep tooltip content concise, ideally one or two sentences.
  • Avoid putting essential instructions only in a tooltip.

Accessibility

  • Associate standalone labels with controls using for/htmlFor and a matching control id.
  • Tooltip triggers are keyboard focusable through the info button.
  • The info icon button has an accessible label: “More information”.
  • Use clear, descriptive label text for every form control.