<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>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.
| 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. |
optionalLabel | string | LocaleProvider text | Overrides the optional marker. Empty text hides the marker text. |
optionalLabel | slot | - | Rich optional-marker content. Takes precedence over the prop and provider. |
tooltip | string | - | Tooltip text shown from the info icon. |
tooltipAriaLabel | string | LocaleProvider text | Overrides the tooltip button's accessible name. |
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
htmlForor a wrapping label to associate custom labels with controls.