components / textfield

TextField

Single-line field shell with DK field tokens, helper/error support, and leading/trailing slots.

Overview

What it is

This section explains the intent of the component before the implementation details.

  • TextField is the baseline DK field shell and the reference point for most labeled input behavior across the system.
  • Use it when the user is entering a single line of text that benefits from clear labeling, helper copy, and validation feedback.

Aliases

input, text input

Decision guide

How to choose it

Use these notes to decide quickly whether this is the right DK component for the job.

Decision guide

  • Choose TextField when the interaction should feel deliberate, documented, and reusable across product surfaces.
  • If the scenario is more specialized than the current TextField contract, prefer a simpler component or build a dedicated workflow on top of the lower-level DK primitives.

Do

  • Keep the TextField label, value, or status language direct enough to scan quickly.
  • Use the documented size and state recipes instead of inventing one-off variants in product code.

Do not

  • Do not hide the main purpose of TextField behind decorative copy or overloaded surface treatments.
  • Do not stretch TextField into a workflow it was not designed to handle just because the visuals are close.

Usage

When to use

Prefer these situations when choosing this component.

  • Use TextField for short text input like names, labels, identifiers, and small metadata values.
  • Use leading and trailing slots for compact contextual cues such as prefixes, status markers, or units.

Usage

When not to use

These patterns are better served by a different component or a simpler surface.

  • Do not use TextField for multi-line text; use Textarea.
  • Do not overload the field with too many decorative add-ons that compete with the label.

Anti-patterns

  • Using TextField as a generic layout container instead of a purpose-built interaction or content surface.
  • Forking the documented recipe in product code instead of extending the shared DK contract.

Migration notes

  • Migrate legacy textfield usage by mapping existing variants and states onto the documented DK props before porting any custom styling.
  • Treat the docs examples as the reference contract for accessibility and event behavior during adoption.

Anatomy

Structural parts

The anatomy explains which pieces matter to the recipe and accessibility model.

field wrapper

root

Owns label, helper text, error text, and control grouping.

field label

label

Names the input clearly.

native text input

control

Single-line input element using DK field tokens.

supporting slot

leading

Optional prefix or icon before the value.

supporting slot

trailing

Optional suffix or small status marker after the value.

API

Public interface

The docs contract distinguishes props, DOM events, and slots so integration behavior is explicit.

Props

NameTypeDefaultDescription
labelstring—Visible label used for the field or control.
descriptionstring—Supporting helper copy rendered below or beside the main label.
errorstring—Validation or problem copy rendered in the error slot when present.
placeholderstring—Placeholder text shown before a user makes a selection or enters text.
requiredbooleanfalseMarks the field or control as required for form semantics and docs examples.
disabledbooleanfalseDisables interaction and exposes the correct non-interactive semantics for the control.
namestring—Form field name used for native form submission.
idstring—Optional id used to bind external labels or descriptions to the component.
size'sm' | 'md' | 'lg''md'Chooses the compiled size recipe for the component.
readonlybooleanfalseKeeps the field focusable while preventing edits.
typestring'text'Native input type.
valuestring—Controlled text value.
onChange(detail: { value: string | undefined }) => void—Callback fired when the value changes.
themeThemeContract—Overrides the compiled DK theme used to resolve tokens and recipes for this component.

Events

NamePayloadDescription
change{ value: string | undefined }Fires when the component commits a new value.

Slots

NameDescription
leadingOptional prefix or icon.
trailingOptional suffix or status marker.

Recipes

Variants, sizes, and states

These notes summarize the intended recipe surface rather than exposing raw implementation detail first.

Variants

  • default: TextField uses one structural field shell and varies mainly by size and state.

Sizes

  • sm: Compact field shell for denser tools.
  • md: Default field size for general product use.
  • lg: Larger field shell for spacious or touch-oriented layouts.

States

  • rest: Default field shell.
  • focus-visible: Focused input with visible keyboard affordance.
  • invalid: Validation state with error messaging.
  • disabled: Semantically disabled and visibly muted.

Accessibility

Accessibility contract

This is the behavior the component promises to assistive tech and keyboard users today.

Semantics

  • Uses standard field labeling through visible labels, descriptions, and error text.
  • Exposes disabled and required semantics through the underlying form control.

Keyboard

  • Supports native focus and text entry behavior.
  • Supports native text editing, focus movement, and selection behavior.

Screen readers

  • Connects visible label, helper text, and error text to the native control.

Checklist

  • Verify the visible label or title still produces a clear accessible name.
  • Verify focus remains obvious in every supported state and size.
  • Verify disabled, selected, and error states do not rely on color alone.

Implementation

Tokens and slot vars

This section shows the representative compiled slot variables that the runtime consumes for the selected design system.

root

--dk-field-stack-gap
0.45rem
--dk-field-addon-gap
0.5rem

label

--dk-field-label-color
#16181c
--dk-field-label-size
clamp(1.333rem, 1.2222rem + 0.494vw, 1.667rem)
--dk-field-label-weight
600

field

--dk-text-field-bg
#f2f5fb
--dk-text-field-fg
#16181c
--dk-text-field-border
#95989d
--dk-text-field-border-width
1px
--dk-text-field-radius
clamp(0.75rem, 0.6875rem + 0.278vw, 0.938rem)
--dk-text-field-block-size
48px
--dk-text-field-inline-padding
clamp(1.333rem, 1.2222rem + 0.494vw, 1.667rem)
--dk-text-field-input-font-size
clamp(1.333rem, 1.2222rem + 0.494vw, 1.667rem)
--dk-text-field-placeholder
#95989d
--dk-text-field-shadow
none
--dk-text-field-focus-ring-color
#2072e4
--dk-text-field-motion-duration
200ms

description

--dk-field-description-color
#16181c
--dk-field-description-size
0.8125rem

error

--dk-field-error-color
#cc272e
--dk-field-error-size
0.8125rem

leading

--dk-text-field-addon-color
#16181c
--dk-text-field-addon-size
1rem

trailing

--dk-text-field-addon-color
#16181c
--dk-text-field-addon-size
1rem

Implementation notes

  • TextField is the baseline field contract. Most other field-like components inherit its labeling and helper/error expectations.

Implementation checklist

  • Use the public component API first and only drop to lower-level primitives when the component contract genuinely does not fit.
  • Keep theme overrides token-driven so proofs and recipes stay meaningful.
  • Verify the shipped examples and proof fixtures still represent the real product scenario you are implementing.

Examples

Copy-paste examples

Each example is intentionally practical, grouped by starter, common pattern, and edge-case coverage.

Examples
3
Depth
baseline

Starter

1 example

starter

Starter: labeled single-line input

A basic project-name input with helper text.

Copy snippet

<TextField label="Project name" description="Use a short name the team can scan quickly." placeholder="Launch roadmap" />

Common patterns

1 example

common

Common: prefixed metadata field

Leading and trailing slots help compact metadata entry without custom chrome.

Copy snippet

<TextField label="Project key" placeholder="APOLLO"><svelte:fragment slot="leading">#</svelte:fragment><svelte:fragment slot="trailing">ok</svelte:fragment></TextField>

Edge cases

1 example

edge

Edge: inline validation

Use the error slot when the field needs explicit corrective feedback.

Copy snippet

<TextField label="Project name" error="A project name is required." placeholder="Launch roadmap" />

Verification

Curated proof fixtures

Proofs stay visible in the docs so the system shows what it can guarantee, not just what it can render.

sizes (size=xs)

pass

size=xs

  • Contrast: 98.5 Lc, 49.2 Lc
  • Target: 44px
  • Layout: 209 / 240, 320, 420
  • Helper: 2/2, 2/1

sizes (size=sm)

pass

size=sm

  • Contrast: 98.5 Lc, 49.2 Lc
  • Target: 44px
  • Layout: 188 / 240, 320, 420
  • Helper: 2/2, 2/1

sizes (size=md)

pass

size=md

  • Contrast: 98.5 Lc, 49.2 Lc
  • Target: 48px
  • Layout: 233 / 240, 320, 420
  • Helper: 2/2, 2/1

sizes (size=lg)

pass

size=lg

  • Contrast: 98.5 Lc, 49.2 Lc
  • Target: 52px
  • Layout: 310 / 240, 320, 420
  • Helper: 2/2, 2/1

invalid-md

pass

size=md

  • Contrast: 98.5 Lc, 49.2 Lc
  • Target: 48px
  • Layout: 233 / 240, 320, 420
  • Helper: 2/2, 2/1

disabled-sm

pass

size=sm

  • Contrast: 90.8 Lc, 41.5 Lc
  • Target: 44px
  • Layout: 188 / 240, 320, 420
  • Helper: 2/2, 2/1