---
title: Label
description: Displays a form label with optional indicator and tooltip support.
order: 18
tags: [components]
---

import { Preview } from "$lib/components/preview";
import { Checkbox, Input, Label, Select } from "areia";

# Label

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

[Source Code](https://github.com/ilhajs/areia/blob/main/packages/areia/src/components/label/index.ts)

<Preview
  code={
    'import ilha from "ilha";\nimport { Label } from "areia";\n\nexport default ilha.render(() => (\n  <div class="flex flex-col gap-3">\n    <Label for="default-label-demo" label="Default Label" />\n    <Label\n      for="optional-label-demo"\n      label="Optional Label"\n      showOptional\n    />\n    <Label\n      for="tooltip-label-demo"\n      label="Label with Tooltip"\n      tooltip="Helpful context about this field."\n    />\n  </div>\n));'
  }
  lang="tsx"
>
  <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>
</Preview>

## Import

```ts
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.

<Preview
  code={
    'import ilha from "ilha";\nimport { Input } from "areia";\n\nexport default ilha.render(() => (\n  <div class="flex w-full max-w-sm flex-col gap-4">\n    <Input\n      id="middle-name"\n      label="Middle name"\n      required={false}\n      placeholder="Ada"\n    />\n    <Input\n      id="email-updates"\n      label="Email"\n      labelTooltip="We\'ll only use this for account notifications."\n      placeholder="you@example.com"\n      type="email"\n    />\n  </div>\n));'
  }
  lang="tsx"
>
  <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>
</Preview>

### Standalone Label

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

<Preview
  code={
    'import ilha from "ilha";\nimport { Input, Label } from "areia";\n\nexport default ilha.render(() => (\n  <div class="flex w-full max-w-sm flex-col gap-1.5">\n    <Label for="username" label="Username" />\n    <Input id="username" placeholder="areia-user" />\n  </div>\n));'
  }
  lang="tsx"
>
  <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>
</Preview>

## Examples

### Optional Field

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

<Preview
  code={
    'import ilha from "ilha";\nimport { Input, Label } from "areia";\n\nexport default ilha.render(() => (\n  <div class="flex w-full max-w-sm flex-col gap-1.5">\n    <Label for="nickname" label="Nickname" showOptional />\n    <Input id="nickname" placeholder="Ryuz" />\n  </div>\n));'
  }
  lang="tsx"
>
  <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>
</Preview>

### With Tooltip

Use `tooltip` to show an info icon with additional context.

<Preview
  code={
    'import ilha from "ilha";\nimport { Input, Label } from "areia";\n\nexport default ilha.render(() => (\n  <div class="flex w-full max-w-sm flex-col gap-1.5">\n    <Label\n      for="email"\n      label="Email"\n      tooltip="We\'ll use this to send you product and account updates."\n    />\n    <Input\n      id="email"\n      type="email"\n      placeholder="you@example.com"\n    />\n  </div>\n));'
  }
  lang="tsx"
>
  <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>
</Preview>

### Rich Label Content

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

<Preview
  code={
    'import ilha from "ilha";\nimport { Label, Checkbox } from "areia";\n\nexport default ilha.render(() => (\n  <Checkbox.Item\n    value="terms"\n    label={\n      <Label asContent>\n        I agree to the <strong>Terms of Service</strong>\n      </Label>\n    }\n  />\n));'
  }
  lang="tsx"
>
  <Checkbox.Item
    value="terms"
    label={
      <Label asContent>
        I agree to the <strong>Terms of Service</strong>
      </Label>
    }
  />
</Preview>

### Form with Mixed Fields

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

<Preview code={"import ilha from \"ilha\";\nimport { Input, Label, Select } from \"areia\";\n\nexport default ilha.render(() => (\n  <form class=\"flex w-full max-w-sm flex-col gap-4\">\n    <Input\n      id=\"full-name\"\n      label=\"Full name\"\n      required\n      placeholder=\"Ada Lovelace\"\n    />\n\n    <div class=\"flex flex-col gap-1.5\">\n      <Label for=\"company\" label=\"Company\" showOptional />\n      <Input id=\"company\" placeholder=\"Areia Labs\" />\n    </div>\n\n    <Select\n      id=\"country\"\n      label=\"Country\"\n      placeholder=\"Select a country\"\n      items={{\n        us: \"United States\",\n        uk: \"United Kingdom\",\n        ca: \"Canada\",\n      }}\n    />\n  </form>\n));"} lang="tsx">
  <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>

</Preview>

### As Content

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

<Preview
  code={
    'import ilha from "ilha";\nimport { Label } from "areia";\n\nexport default ilha.render(() => (\n  <label class="text-base font-medium text-areia-default">\n    <Label\n      asContent\n      label="Project slug"\n      showOptional\n      tooltip="Used in generated URLs. You can change it later."\n    />\n  </label>\n));'
  }
  lang="tsx"
>
  <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>
</Preview>

## API Reference

### Label

Extends native label attributes.

| Prop           | Type      | Default | Description                                                             |
| -------------- | --------- | ------- | ----------------------------------------------------------------------- |
| `children`     | `unknown` | -       | Label content. Takes precedence over `label`.                           |
| `label`        | `unknown` | -       | Label content used when `children` is not provided.                     |
| `showOptional` | `boolean` | `false` | Shows subtle “(optional)” text after the label.                         |
| `tooltip`      | `unknown` | -       | Tooltip content shown through an info icon next to the label.           |
| `for`          | `string`  | -       | The id of the form element this label is associated with.               |
| `htmlFor`      | `string`  | -       | Alias for `for`, useful when matching React-style prop naming.          |
| `asContent`    | `boolean` | `false` | Renders only inline label content in a `<span>` instead of a `<label>`. |
| `class`        | `string`  | -       | Additional CSS classes merged with the generated classes.               |
| `className`    | `string`  | -       | 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.

| Prop           | Type      | Default | Description                                                                         |
| -------------- | --------- | ------- | ----------------------------------------------------------------------------------- |
| `label`        | `unknown` | -       | Label content. Enables the component’s field wrapper.                               |
| `required`     | `boolean` | -       | Sets the native required state; `false` may show optional text on supported fields. |
| `labelTooltip` | `string`  | -       | 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.