Phi
Phi
Input
@dicehub/phiv1.0.0-beta.1

Input

A text input field for user input with built-in label, description, and error support.

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

<template>
  <Input
    label="Email"
    placeholder="[email protected]"
    description="We'll never share your email"
  />
</template>

Installation

Barrel

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

Granular

import { Input } from "@dicehub/phi/components/input";

Usage

Use label, description, or error to render the built-in field wrapper and wire the control to accessible text.

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

<template>
  <Input
    label="Email"
    placeholder="[email protected]"
    description="We'll never share your email"
  />
</template>

Bare Input (Custom Layouts)

Use a bare input when another layout owns the label. Always provide aria-labelor aria-labelledby.

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

<template>
  <Input placeholder="Search..." aria-label="Search products" />
</template>

Examples

With Label and Description

Use the built-in field wrapper for accessible labels and helper text.

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

<template>
  <Input
    label="Username"
    placeholder="Choose a username"
    description="3-20 characters, alphanumeric only"
  />
</template>

With Error (String)

Passing an error string displays the message and applies the error ring.

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

<template>
  <Input
    label="Email"
    placeholder="[email protected]"
    default-value="invalid-email"
    error="Please enter a valid email address"
  />
</template>

With Error (Validation Object)

Structured errors provide message and validity-match fields for validation use cases.

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

<template>
  <Input
    label="Password"
    type="password"
    default-value="short"
    :error="{ message: 'Password must be at least 8 characters', match: 'tooShort' }"
    :minlength="8"
  />
</template>

Input Sizes

Inputs support xs, sm, base, and lg sizes.

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

<template>
  <div class="stack">
    <Input size="xs" label="Extra Small" placeholder="Extra small input" />
    <Input size="sm" label="Small" placeholder="Small input" />
    <Input label="Base" placeholder="Base input (default)" />
    <Input size="lg" label="Large" placeholder="Large input" />
  </div>
</template>

Disabled

Disabled inputs keep the same layout and mute the editable text state.

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

<template>
  <Input label="Disabled field" placeholder="Cannot edit" disabled />
</template>

Optional Field

Set required to false to show the "(optional)" label marker.

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

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

With Label Tooltip

Use labelTooltip for compact field guidance next to the label.

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

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

Rich Label

Use the label slot when the label needs inline markup.

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

<template>
  <Input required placeholder="[email protected]" type="email">
    <template #label>
      <span>Email for <strong>billing</strong></span>
    </template>
  </Input>
</template>

Controlled with v-model

Bind the value with Vue's v-model syntax.

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

const value = ref("");
</script>

<template>
  <Input
    v-model="value"
    label="With v-model"
    placeholder="Type something..."
    :description="value ? `Value: ${value}` : 'Uses v-model'"
  />
</template>

Controlled with valueChange

Use valueChange when a string-only change event is more convenient.

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

const value = ref("");
</script>

<template>
  <Input
    :model-value="value"
    label="With valueChange"
    placeholder="Type something..."
    :description="value ? `Value: ${value}` : 'Receives the value directly'"
    @value-change="value = $event"
  />
</template>

Bare Input (No Label)

For custom layouts, provide an accessible name with aria-label or aria-labelledby.

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

<template>
  <Input placeholder="Search..." aria-label="Search products" />
</template>

Error Without Label

Bare inputs can still show errors when they have an accessible name.

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

<template>
  <div class="stack">
    <Input
      aria-label="Hostname"
      placeholder="example.com"
      default-value="not a host"
      error="Please enter a valid hostname"
    />
    <Input
      aria-label="Path"
      placeholder="/api/v1/users"
      default-value="missing-slash"
      :error="{ message: 'Path must start with /', match: true }"
    />
  </div>
</template>

Input Types

Forward native input types such as email, password, number, and tel.

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

<template>
  <div class="stack">
    <Input type="email" label="Email" placeholder="[email protected]" />
    <Input type="password" label="Password" placeholder="••••••••" />
    <Input type="number" label="Age" placeholder="18" />
    <Input type="tel" label="Phone" placeholder="+1 (555) 000-0000" />
  </div>
</template>

Password Manager Overlays

Set passwordManagerIgnore to add common password manager suppression attributes.

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

<template>
  <div class="stack">
    <Input label="API Key (default)" type="password" placeholder="sk_live_..." />
    <Input
      label="API Key (passwordManagerIgnore)"
      type="password"
      placeholder="sk_live_..."
      password-manager-ignore
    />
  </div>
</template>

API Reference

Input accepts native HTML input attributes plus the following:

Props

PropTypeDefaultDescription
modelValuestring | number-Controlled value used by v-model.
defaultValuestring | number-Initial value for uncontrolled inputs.
labelstring-Visible field label. Enables the field wrapper.
descriptionstring-Helper text shown below the input when there is no error.
errorstring | { message: string; match?: InputErrorMatch }-Validation error message. Also applies error styling.
invalidbooleanfalseMarks the input invalid without requiring an error message.
size"xs" | "sm" | "base" | "lg""base"Controls height, padding, radius, and text size.
variant"default" | "error""default"Visual variant. Prefer the error prop for validation.
typestring"text"Native input type.
placeholderstring-Native placeholder text.
requiredboolean-Native required state. Set false to show "(optional)".
disabledbooleanfalseDisables the input.
readOnlybooleanfalseApplies the native readonly attribute.
passwordManagerIgnorebooleanfalseAdds data attributes and keeper-ignore for password manager suppression.
$attrsInputHTMLAttributes-Native input attributes such as aria-label, autocomplete, minLength, and pattern.

Slots

SlotDescription
labelOverrides the label prop with custom label markup.
descriptionOverrides the description prop with custom helper markup.
errorOverrides the error message with custom error markup.

Events

EventTypeDescription
update:modelValue(value: string) => voidEmitted on native input for v-model.
valueChange(value: string) => voidString-only convenience change event.

Validation Error Types

Structured errors accept a browser validity match key. Phi displays the message directly and keeps the shape suitable for native validity checks.

Match
boolean
badInput
customError
patternMismatch
rangeOverflow
rangeUnderflow
stepMismatch
tooLong
tooShort
typeMismatch
valid
valueMissing

Accessibility

Label Requirement

Prefer the label prop or label slot. If the visible label lives outside Input, provide aria-label or aria-labelledby.

Error Association

When error is present, Input sets aria-invalid and associates the message through aria-describedby.