Phi / Label

<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

With Form Components (Recommended)

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>

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>

API Reference

Label Props

Props for the standalone Label component.

Prop	Type	Default	Description
`default`	`slot`	`-`	Label content.
`htmlFor`	`string`	`-`	ID of the form control this label is associated with. In templates, use html-for.
`showOptional`	`boolean`	`false`	Shows gray "(optional)" text after the label.
`tooltip`	`string`	`-`	Tooltip text shown from the info icon.
`as`	`"label" \| "span"`	`"label"`	Element rendered by the root.
`asContent`	`boolean`	`false`	Renders 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.

Prop	Type	Default	Description
`label`	`string \| slot`	`-`	Label content for built-in field wrappers.
`required`	`boolean`	`-`	When false, shows "(optional)" text and keeps the control optional.
`labelTooltip`	`string`	`-`	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.