Phila TextField Component

A text input with an optional label, leading/trailing icons, a built-in clear button, supporting text, and error messaging. Supports both v-model (controlled) and uncontrolled use, plus optional input masking via imaskProps.

Features

• 🎨 Customizable label, placeholder, and supporting text
• 🔄 Optional leading and trailing icons
• 🧹 Built-in clear button (icon-only) when input has content
• 📏 Dynamic error handling with customizable messages
• ♿ Accessibility features: focus states, disabled state

Installation

pnpm add @phila/phila-ui-text-field @phila/phila-ui-core @phila/phila-ui-button
# or
npm install @phila/phila-ui-text-field @phila/phila-ui-core @phila/phila-ui-button

Import core styles in your main entry file (e.g., main.js|ts):

import "@phila/phila-ui-core/styles/template-light.css";

Usage

Use the TextField component with the appropriate props. You can customize the label, placeholder, icons, and error messages.

<script setup lang="ts">
import { ref } from "vue";
import { TextField } from "@phila/phila-ui-text-field";
import { IconMagnifyingGlass, IconPhone } from "@phila/phila-ui-core/icons";

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

<template>
  <TextField
    v-model="name"
    label="Your Name"
    placeholder="Enter your name"
    supporting-text="This is a required field"
    :leading-icon="IconMagnifyingGlass"
    :trailing-icon="IconPhone"
    :error="['Name is required']"
    required
  />
</template>

Masked input

Pass an imask mask via imaskProps to constrain/format input as the user types (e.g. a phone number), and listen for complete when the mask is fully satisfied:

<TextField label="Phone" :imask-props="{ mask: '(000) 000-0000' }" @complete="onComplete" />

Props

| Prop | Type | Default | Description | | ---------------- | ------------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | modelValue | string | undefined | Bound value (v-model). Works uncontrolled too — omit it and the field manages its own value internally. | | label | string | "" | Label text for the input field | | placeholder | string | "" | Placeholder text when the input is empty | | supportingText | string | "" | Helper text shown below the input | | leadingIcon | IconComponent | undefined | Icon shown before the input, from @phila/phila-ui-core/icons. | | trailingIcon | IconComponent | undefined | Icon shown after the input, from @phila/phila-ui-core/icons. | | error | string \| string[] | [] | Error message(s). Only the first is displayed, even if an array with several entries is passed. | | imaskProps | Record<string, unknown> | undefined | imask options (e.g. { mask: '(000) 000-0000' }). A mask key switches to a masked input and enables the complete event. | | id | string | auto-generated | ID for the input element | | className | string | "" | Additional CSS classes | | disabled | boolean | false | Not a declared prop — passed through as a native HTML attribute and detected via useAttrs() for styling. | | required | boolean | false | Same as disabled — a native attribute, not a declared prop. |

Note: The TextField component automatically displays a clear button (icon-only Button component) when the input has content.

Slots

| Slot | Description | | ----------------- | -------------------------------------------------------------------------- | | trailing-action | Extra content after the trailing icon/clear button (e.g. a custom action). |

Events

| Event | Payload | Description | | ------------------- | -------- | ------------------------------------------------------------------------------------- | | update:modelValue | string | Emitted on input, for v-model. | | complete | string | Masked input only (imaskProps.mask set) — emitted when the mask is fully satisfied. |

Exposed

Access via a template ref on TextField:

| Property | Type | Description | | ---------- | ------------------------------- | ---------------------------------------- | | inputRef | Ref<HTMLInputElement \| null> | The underlying native <input> element. |

Development

Install Dependencies

pnpm install

Run Demo

pnpm dev

Run lint

pnpm lint

Create Production Build

pnpm build

Test locally in your development environment

npm pack
cp ./dist/*.tgz ~/path/to/your/local/npm/repo
cd ~/path/to/your/local/npm/repo
npm install *.tgz

Publishing to NPM

Follow the release instructions using changesets.

License

MIT