Skip to content
Kappa
Kappa
Label
@dicehub/kappav0.4.2

Label

Names a native form control with clear association and compact Kappa typography.

<script setup>
import { Label } from "@dicehub/kappa/components/label";
</script>

<template>
  <Label for="username">Username</Label>
  <input id="username" name="username" value="jordanlee" autocomplete="username" />
</template>

Installation

Label is part of the main Kappa package. It renders native HTML and has no Ark UI state machine or additional runtime dependency.

Barrel

import { Label } from "@dicehub/kappa";

Granular

import { Label } from "@dicehub/kappa/components/label";

Usage

Match for to the control id. A click on the visible text then focuses or activates the control. Label forwards native attributes, data attributes, event listeners, and consumer classes to its root.

<script setup>
import { Label } from "@dicehub/kappa/components/label";
</script>

<template>
  <Label for="email">Email address</Label>
  <input id="email" name="email" type="email" autocomplete="email" />
</template>

Composition

Rendered structure
Label <label | span>
└── optional marker [data-slot="label-optional"] (when showOptional)

Ark UI has no separate Label primitive; its labels belong to components such asField.

  • Use standalone Label with a native control that already owns its state and messages.
  • Use Field.Label for required, invalid, disabled, helper, or error state.
  • Use a compound control's connected label, such as Checkbox.Label, when one exists.
  • asContent provides Kappa text inside that connected label without nesting labels.

Label does not include a tooltip prop. Do not place a focusable help trigger inside a native label. Put persistent guidance after the control or compose a separate Tooltip trigger.

Examples

Optional Text

Use showOptional only when optional fields need explicit contrast. TranslateoptionalText for the current locale.

<Label for="extension" show-optional>Extension</Label>
<input id="extension" name="extension" inputmode="numeric" />

<Label for="nickname" show-optional optional-text="facultatif">Surnom</Label>
<input id="nickname" name="nickname" lang="fr" />

htmlFor Alias

Use native for in Vue templates. htmlFor is an alias for generated prop objects.

<Label html-for="account-name">Account name</Label>
<input id="account-name" name="account-name" />

Wrapped Control

A native label can wrap a simple control when a separate id association is not useful.

<Label class="checkbox-row">
  <input name="remember-device" type="checkbox" />
  Remember this device
</Label>

Content Composition

Use asContent inside a compound control label. It renders a span and inherits the surrounding type treatment, so the document contains only one semantic label.

<script setup>
import { Checkbox } from "@dicehub/kappa/components/checkbox";
import { Label } from "@dicehub/kappa/components/label";
</script>

<template>
  <Checkbox.Root name="analytics" default-checked>
    <Checkbox.Control />
    <Checkbox.Label>
      <Label as-content>Share anonymous usage data</Label>
    </Checkbox.Label>
  </Checkbox.Root>
</template>

Persistent Guidance

Keep important instructions visible and connect them with aria-describedby. Use Field when the application also needs shared validation or disabled state.

Use the 8-character code from your invitation email.

<Label for="invite-code">Invite code</Label>
<input id="invite-code" name="invite-code" aria-describedby="invite-code-help" />
<p id="invite-code-help">Use the 8-character code from your invitation email.</p>

Disabled

Native labels have no disabled attribute. Disable the control and adddata-disabled or aria-disabled="true" to Label for matching presentation.

<Label for="member-id" data-disabled>Member ID</Label>
<input id="member-id" name="member-id" value="MBR-2841" disabled />

Right to Left

Logical layout and inline spacing follow the inherited writing direction.

<div dir="rtl" lang="ar">
  <Label for="city" show-optional optional-text="اختياري">المدينة</Label>
  <input id="city" name="city" value="عمّان" />
</div>

Accessibility

  • Give every form control a concise accessible name. Keep visible labels whenever possible.
  • Match for and id, or wrap a simple native control.
  • Do not use a bare span as the only accessible label for a native control.
  • Optional text is visual guidance. The control's native required state remains authoritative.
  • Do not place buttons, links, or tooltip triggers inside a native label.
  • Translate both visible label text and optionalText.

API Reference

Label

Renders a native label by default. Native attributes and listeners pass to the root.

PropTypeDefaultDescription
as"label" | "span""label"Selects the native root element.
asContentbooleanfalseRenders a span and inherits surrounding typography for nested composition.
htmlForstring—Associates a native label with a control id. Native `for` is also supported.
showOptionalbooleanfalseShows a quiet optional marker after the default slot.
optionalTextstring"optional"Sets translated text inside the optional marker.

Slots

SlotDescription
defaultVisible label text or content. Keep the accessible name concise.

Data Slots

SlotElementDescription
labellabel | spanRoot label or content element.
label-optionalspanOptional marker rendered when showOptional is true.

Exports

ExportDescription
LabelNative standalone form label component.
LabelProps / LabelSlotsPublic prop and slot contracts.
LabelElementSupported label and span root elements.
LABEL_ELEMENTSSupported native root elements.
LABEL_DEFAULT_ELEMENTDefault native label root.
LABEL_DEFAULT_OPTIONAL_TEXTDefault optional marker text.
isLabelElementSupported-element type guard.
resolveLabelElementSafe root-element resolver.
resolveLabelOptionalTextSafe optional-text resolver.