Skip to content

FormField

Wrapper that adds a label, description or error text, and a required indicator around any input component. Spread the attributes supplied to the children snippet onto the focusable input for automatic label and description/error linkage.

import { FormField, TextInput } from "phoundry-ui";

Basic with Label

Loading interactive example…

View source
basic-with-label.svelte
<script lang="ts">
import { FormField } from "phoundry-ui";
import { TextInput } from "phoundry-ui";
let basic = $state("");
</script>
<div class="max-w-sm">
<FormField label="Username" id="doc-username">
{#snippet children(control)}
<TextInput
{...control}
value={basic}
oninput={(v: string) => {
basic = v;
}}
placeholder="Enter username"
/>
{/snippet}
</FormField>
</div>

With Description

Loading interactive example…

View source
with-description.svelte
<script lang="ts">
import { FormField } from "phoundry-ui";
import { TextInput } from "phoundry-ui";
let desc = $state("");
</script>
<div class="max-w-sm">
<FormField
label="Email"
id="doc-email"
description="We'll never share your email."
>
{#snippet children(control)}
<TextInput
{...control}
value={desc}
oninput={(v: string) => {
desc = v;
}}
placeholder="you@example.com"
/>
{/snippet}
</FormField>
</div>

With Error

Loading interactive example…

View source
with-error.svelte
<script lang="ts">
import { FormField } from "phoundry-ui";
import { TextInput } from "phoundry-ui";
let errorVal = $state("");
</script>
<div class="max-w-sm">
<FormField
label="Password"
id="doc-password"
error="Password must be at least 8 characters."
>
{#snippet children(control)}
<TextInput
{...control}
type="password"
value={errorVal}
oninput={(v: string) => {
errorVal = v;
}}
placeholder="Enter password"
/>
{/snippet}
</FormField>
</div>

Required

Loading interactive example…

View source
required.svelte
<script lang="ts">
import { FormField } from "phoundry-ui";
import { TextInput } from "phoundry-ui";
let req = $state("");
</script>
<div class="max-w-sm">
<FormField label="Full Name" id="doc-fullname" required>
{#snippet children(control)}
<TextInput
{...control}
value={req}
oninput={(v: string) => {
req = v;
}}
placeholder="Jane Doe"
/>
{/snippet}
</FormField>
</div>

Snippet label

Loading interactive example…

View source
snippet-label.svelte
<script lang="ts">
import { FormField } from "phoundry-ui";
import { TextInput } from "phoundry-ui";
let apiKey = $state("");
</script>
{#snippet labelSnippet()}
API Key <span class="text-txt-tertiary">(scoped)</span>
{/snippet}
<div class="max-w-sm">
<FormField
label={labelSnippet}
id="doc-apikey"
description="Rich labels still associate correctly when ids match."
>
{#snippet children(control)}
<TextInput
{...control}
value={apiKey}
oninput={(v: string) => {
apiKey = v;
}}
placeholder="pk_live_…"
/>
{/snippet}
</FormField>
</div>

API

From phoundry-ui@0.4.21

NameTypeDefaultDescription
labelstring | Snippet<[]>—Field label text or custom snippet.
descriptionstring—Helper text shown below the input.
errorstring—Error message - replaces description when present.
requiredbooleanfalseShows a red asterisk next to the label.
disabledbooleanfalseDims the wrapper only. Pass disabled to the actual control to prevent interaction.
idstring—HTML id for the label’s for attribute. Auto-generated if omitted.
classClassValue—Additional CSS classes on the wrapper.
stylestring—Inline styles on the stable component root.
childrenrequiredSnippet<[FormFieldControl]>—Render one focusable control and spread the supplied id and ARIA attributes onto it.

Usage tips

  • The error prop takes priority over description - only one displays at a time.
  • Use {#snippet children(control)} and spread {...control} onto the focusable input. This links the label, helper/error text, invalid state, and required semantics, including when id is generated.
  • Pass a Snippet for label when you need custom markup (e.g. an icon next to the label text).
  • Wrap any input component - TextInput, Select, Textarea, etc.

Styling

.ph-form-field is the stable root hook. Consumer class values are additive, and style applies to that root. Styling uses vanilla CSS with semantic state attributes. Label and description/error IDs remain linked through the children(control) snippet. Spread those supplied attributes onto the one focusable input. Generated IDs are stable across server rendering and hydration. disabled dims the wrapper; disable the actual control separately. The wrapper emits data-disabled; helper text emits data-error. Internal part selectors and --_ph-* properties remain implementation details.

Documentation is licensed under CC BY 4.0. Phoundry names and marks remain reserved.