Phi
Label
@dicehub/phiv1.7.0

Label

A label component for form fields with optional indicators and tooltips.

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

<template>
  <div class="flex flex-col gap-4">
    <Label>Default Label</Label>
    <Label show-optional>Optional Label</Label>
    <Label tooltip="More information about this field">
      Label with Tooltip
    </Label>
  </div>
</template>

Installation

Barrel

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

Granular

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

Usage

Label features are available through form components like Input, InputArea, and InputGroup via the required and labelTooltip props.

<script setup>
import { Input } from "@dicehub/phi/components/input";
</script>

<template>
  <!-- Optional field with "(optional)" text -->
  <Input label="Phone" :required="false" placeholder="+1 555-0000" />

  <!-- With tooltip -->
  <Input
    label="API Key"
    label-tooltip="Find this in your dashboard settings"
  />
</template>

Standalone Label

For custom form layouts, use the Label component directly.

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

<template>
  <Label tooltip="This field is mandatory">Username</Label>
</template>

Examples

Optional Field

Shows gray "(optional)" text when required is false.

<script setup>
import { Input } from "@dicehub/phi/components/input";
</script>

<template>
  <Input label="Phone Number" :required="false" placeholder="+1 555-0000" />
</template>

With Tooltip

Shows an info icon with a tooltip for additional context.

<script setup>
import { Input } from "@dicehub/phi/components/input";
</script>

<template>
  <Input
    label="API Key"
    label-tooltip="Find this in your dashboard settings under API > Keys"
    placeholder="sk_live_..."
  />
</template>

Rich Label Content

Labels support slot content for rich formatting.

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

<template>
  <Checkbox default-checked>
    <span>I agree to the <strong>Terms of Service</strong></span>
  </Checkbox>
</template>

Form with Mixed Fields

Real-world example showing required and optional fields together.

<script setup>
import { Select, createListCollection as createSelectCollection } from "@ark-ui/vue/select";
import { Input } from "@dicehub/phi/components/input";
import { PhCaretUpDown } from "@phosphor-icons/vue";

const countryItems = [
  { label: "United States", value: "us" },
  { label: "United Kingdom", value: "uk" },
  { label: "Canada", value: "ca" },
];

const countryCollection = createSelectCollection({
  items: countryItems,
  itemToString: (item) => item.label,
  itemToValue: (item) => item.value,
});
</script>

<template>
  <div class="flex max-w-md flex-col gap-4">
    <Input label="Full Name" placeholder="John Doe" />
    <Input
      label="Email"
      label-tooltip="We'll send your receipt here"
      placeholder="[email protected]"
      type="email"
    />
    <Input label="Company" :required="false" placeholder="Acme Inc." />
    <Select.Root :collection="countryCollection">
      <Select.Label>Country</Select.Label>
      <Select.Control>
        <Select.Trigger aria-label="Country">
          <Select.ValueText placeholder="Select a country" />
          <Select.Indicator>
            <PhCaretUpDown :size="16" aria-hidden="true" />
          </Select.Indicator>
        </Select.Trigger>
      </Select.Control>
      <Select.Positioner>
        <Select.Content>
          <Select.Item v-for="country in countryItems" :key="country.value" :item="country">
            <Select.ItemText>{{ country.label }}</Select.ItemText>
          </Select.Item>
        </Select.Content>
      </Select.Positioner>
      <Select.HiddenSelect />
    </Select.Root>
  </div>
</template>

Standalone Label

Use Label directly for custom layouts or non-form contexts.

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

<template>
  <div class="flex flex-col gap-3">
    <Label>Default</Label>
    <Label show-optional>Optional</Label>
    <Label tooltip="Important field">With Tooltip</Label>
  </div>
</template>

Translations

Wrap a form in LocaleProvider to translate optional markers and tooltip accessible names. Label, Input, InputArea, InputGroup, Field, Select, and Checkbox use these translations. Defaults are (optional) and More information.

The provider adds no wrapper element. Translation changes update mounted controls. Nested providers inherit text that they do not override. Use optional-label, theoptionalLabel slot, and tooltip-aria-label for individual Label overrides. These overrides take precedence over provider text.

<script setup>
import { Input, Label, LocaleProvider } from "@dicehub/phi";
const translations = {
  label: { optional: "(opcional)", tooltip: "Mais informações" },
};
</script>

<template>
  <LocaleProvider :translations="translations">
    <Input label="Nome" :required="false" label-tooltip="Ajuda" />
    <Label show-optional tooltip="Ajuda">Nome</Label>
    <Label show-optional optional-label="(custom)" tooltip="Ajuda" tooltip-aria-label="Custom help">
      Custom
    </Label>
    <Label show-optional>
      Rich content
      <template #optionalLabel><strong>(custom rich text)</strong></template>
    </Label>
  </LocaleProvider>
</template>

API Reference

Label Props

Props for the standalone Label component.

PropTypeDefaultDescription
defaultslot-Label content.
htmlForstring-ID of the form control this label is associated with. In templates, use html-for.
showOptionalbooleanfalseShows gray "(optional)" text after the label.
optionalLabelstringLocaleProvider textOverrides the optional marker. Empty text hides the marker text.
optionalLabelslot-Rich optional-marker content. Takes precedence over the prop and provider.
tooltipstring-Tooltip text shown from the info icon.
tooltipAriaLabelstringLocaleProvider textOverrides the tooltip button's accessible name.
as"label" | "span""label"Element rendered by the root.
asContentbooleanfalseRenders inline content styling without standalone label typography.

Form Component Label Props

These props are available on built-in Phi form components that own their field wrapper.

PropTypeDefaultDescription
labelstring | slot-Label content for built-in field wrappers.
requiredboolean-When false, shows "(optional)" text and keeps the control optional.
labelTooltipstring-Tooltip text shown from the label info icon. In templates, use label-tooltip.

Design Guidelines

When to Use Optional Indicators

  • Use "(optional)" for optional fields when most fields are required.
  • Be consistent within a form.
  • Default fields with no indicator are assumed required by users.

When to Use Tooltips

  • Provide additional context that does not fit in the label.
  • Explain format requirements or validation rules.
  • Keep tooltip content concise.

Accessibility

  • Optional indicators are visual. Use native validation props for validation.
  • Tooltip icons are keyboard focusable.
  • Use htmlFor or a wrapping label to associate custom labels with controls.