Aliases
input, text input
TextField
Single-line input with labels, guidance, errors, and icon slots.
Playground
md field shell
# ok
Overview
- Provide a visible label. Add guidance only when it explains input requirements.
Foundations
Type and scale,Spacing,Contrast and distinctness,Proof system
When to use
- Use
TextFieldfor 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.
When not to use
- Do not use
TextFieldfor multiline text; useTextarea. - Do not overload the field with too many decorative add-ons that compete with the label.
Structural parts
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.
Public interface
| Name | Type | Default | Description |
|---|---|---|---|
label | string | — | Visible label used for the field or control. |
description | string | — | Provides field guidance associated with the control. |
error | string | — | Shows a validation error associated with the control. |
placeholder | string | — | Placeholder text shown before a user makes a selection or enters text. |
required | boolean | false | Marks the control as required. |
disabled | boolean | false | Prevents interaction and exposes the disabled state. |
name | string | — | Form field name used for native form submission. |
id | string | — | Sets the control ID for external labels and descriptions. |
size | 'sm' | 'md' | 'lg' | 'md' | Sets the component size. |
readonly | boolean | false | Keeps the field focusable while preventing edits. |
type | string | 'text' | Native input type. |
value | string | — | Controlled text value. |
onChange | (detail: { value: string }) => void | — | Runs when the value changes. |
theme | ThemeContract | — | Sets the theme used to resolve component styles. |
| Name | Payload | Description |
|---|---|---|
change | { value: string } | Fires with the text value. |
| Name | Description |
|---|---|
leading | Optional prefix or icon. |
trailing | Optional suffix or status marker. |
Variants, sizes, and states
Variants
default:TextFielduses 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 a visible outline.invalid: Validation state with error messaging.disabled: Semantically disabled and visibly muted.
Accessibility
Semantics
- Associates the control with its visible label, description, and error.
- 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 that the control has an accessible name.
- Verify that keyboard focus is visible in every state and size.
- Identify disabled, selected, and error states with text or symbols as well as color.
Tokens and CSS variables
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
Examples
Starter
Labeled single-line input
A basic project-name input with helper text.
<TextField label="Project name" description="Use a short project name." placeholder="Launch roadmap" />Common patterns
Prefixed metadata field
Use leading and trailing slots for prefixes, units, or status markers.
<TextField label="Project key" placeholder="APOLLO"><svelte:fragment slot="leading">#</svelte:fragment><svelte:fragment slot="trailing">ok</svelte:fragment></TextField>Edge cases
Inline validation
Set the error prop to explain a validation failure.
<TextField label="Project name" error="A project name is required." placeholder="Launch roadmap" />Mathematical fixtures
Calculated fixtures; browser evidence is not collected. Layout estimates use declared text behavior and maximum token values.
sizes (size=xs)
passsize=xs
- Evidence: mathematical
- Coverage: complete (4 / 4 declared kinds evaluated)
- Declared: contrast, target, layout, helperText
- Evaluated: contrast, target, layout, helperText
- Contrast: 98.5 Lc, 49.2 Lc
- Target: 44 px
- Layout: field · scroll 209 px single-line estimate; 45 px minimum width Values scroll horizontally; full text visibility is not checked. 240 px: pass 1 line; 44 px estimated height320 px: pass 1 line; 44 px estimated height420 px: pass 1 line; 44 px estimated height
- Helper: 2/2, 2/1
sizes (size=sm)
passsize=sm
- Evidence: mathematical
- Coverage: complete (4 / 4 declared kinds evaluated)
- Declared: contrast, target, layout, helperText
- Evaluated: contrast, target, layout, helperText
- Contrast: 98.5 Lc, 49.2 Lc
- Target: 44 px
- Layout: field · scroll 188 px single-line estimate; 65 px minimum width Values scroll horizontally; full text visibility is not checked. 240 px: pass 1 line; 44 px estimated height320 px: pass 1 line; 44 px estimated height420 px: pass 1 line; 44 px estimated height
- Helper: 2/2, 2/1
sizes (size=md)
passsize=md
- Evidence: mathematical
- Coverage: complete (4 / 4 declared kinds evaluated)
- Declared: contrast, target, layout, helperText
- Evaluated: contrast, target, layout, helperText
- Contrast: 98.5 Lc, 49.2 Lc
- Target: 48 px
- Layout: field · scroll 233 px single-line estimate; 68 px minimum width Values scroll horizontally; full text visibility is not checked. 240 px: pass 1 line; 48 px estimated height320 px: pass 1 line; 48 px estimated height420 px: pass 1 line; 48 px estimated height
- Helper: 2/2, 2/1
sizes (size=lg)
passsize=lg
- Evidence: mathematical
- Coverage: complete (4 / 4 declared kinds evaluated)
- Declared: contrast, target, layout, helperText
- Evaluated: contrast, target, layout, helperText
- Contrast: 98.5 Lc, 49.2 Lc
- Target: 52 px
- Layout: field · scroll 310 px single-line estimate; 91 px minimum width Values scroll horizontally; full text visibility is not checked. 240 px: pass 1 line; 52 px estimated height320 px: pass 1 line; 52 px estimated height420 px: pass 1 line; 52 px estimated height
- Helper: 2/2, 2/1
invalid-md
passsize=md
- Evidence: mathematical
- Coverage: complete (4 / 4 declared kinds evaluated)
- Declared: contrast, target, layout, helperText
- Evaluated: contrast, target, layout, helperText
- Contrast: 98.5 Lc, 49.2 Lc
- Target: 48 px
- Layout: field · scroll 233 px single-line estimate; 68 px minimum width Values scroll horizontally; full text visibility is not checked. 240 px: pass 1 line; 48 px estimated height320 px: pass 1 line; 48 px estimated height420 px: pass 1 line; 48 px estimated height
- Helper: 2/2, 2/1
disabled-sm
passsize=sm
- Evidence: mathematical
- Coverage: complete (4 / 4 declared kinds evaluated)
- Declared: contrast, target, layout, helperText
- Evaluated: contrast, target, layout, helperText
- Contrast: 90.8 Lc, 41.5 Lc
- Target: 44 px
- Layout: field · scroll 188 px single-line estimate; 65 px minimum width Values scroll horizontally; full text visibility is not checked. 240 px: pass 1 line; 44 px estimated height320 px: pass 1 line; 44 px estimated height420 px: pass 1 line; 44 px estimated height
- Helper: 2/2, 2/1