Input
import "@taprootio/espalier/input";
<esp-input>
Wraps a standard HTML input field,
providing value binding, input validation, and programmatic
focus for Espalier forms and UIs. It supports several input
types, and has an icon attribute plus a slotted icon escape
hatch.
Inputs pick up zone theming from an ancestor's context attribute —
see the theming guide for theme-defined contexts:
Email validation
Set input-type="email" to get built-in email validation. You
can customize the error message with validation-message:
Number input with min/max
Telephone with locale-aware formatting
The tel type uses phone localities to parse and format phone
numbers on blur. The value is submitted as E.164 (e.g.
"+15551234567"). Use tel-localities to specify which regions
are accepted (space-separated region codes); when omitted, a
sensible default set of 10 common regions is used.
Date input with locale-aware mask
The date type displays a placeholder based on the user's
locale (e.g. "MM/DD/YYYY"). The user types freely and the
input parses the date on blur, submitting the value as
ISO 8601 (2025-01-15).
Slots
<esp-input> has a slot:
Default
Optional custom SVG icon. Slotted icons override the generated SVG from the icon attribute.
Attributes
<esp-input> has the following attributes:
field-name
field-name has a default value of "".
A string value used for the id of the input field.
icon
icon has a default value of "".
Optional icon name from the configured Espalier SVG sprite. Slotted content remains supported and overrides this value.
icon-label
icon-label has a default value of "".
Accessible label for the icon action button. Consumers should
provide a meaningful label whenever icon or a slotted icon
represents an action. The trimmed value is applied as both
aria-label and title; if omitted, the button falls back to
a label derived from icon, then to a generic action label.
input-type
input-type has a default value of "text".
Specifies the type of input, such as text, email, password, etc.
The date type provides a locale-aware placeholder mask —
the user types a date freely, and the value is parsed and
submitted as ISO 8601 on blur. The tel type provides
phone locality matching — the user types digits and
separators, and the value is parsed and submitted as E.164
on blur.
placeholder
placeholder has a default value of undefined.
Placeholder text shown when no value is set. For date
and tel inputs, an explicitly provided placeholder
overrides the locale-derived placeholder. Set
placeholder="" to suppress the derived placeholder.
force-lowercase
force-lowercase has a default value of false.
A boolean value. When true, values the user enters are forced to lowercase.
value
value has a default value of "".
The value of the input. For input-type="date", this is
an ISO 8601 date string (e.g. "2025-06-15"). For
input-type="tel", this is an E.164 phone number
(e.g. "+15551234567").
name
name has a default value of "".
The name used when the input participates in a <form>.
required
required has a default value of false.
When true, the field must have a value before the form can be submitted.
required-message
required-message has a default value of "".
A custom message to display when the field is required but empty.
Defaults to "Please fill out this field." when not set.
validation-message
validation-message has a default value of "".
A custom message to display when the value doesn't match
the expected type or pattern. The default depends on the
input type (e.g. "Please enter a valid email address."
for input-type="email").
disabled
disabled has a default value of false.
When true, the input is disabled and cannot be interacted with.
readonly
readonly has a default value of false.
When true, the input value is submitted with forms but cannot
be edited by the user. The icon action remains enabled unless
disabled is also set.
pattern
pattern has a default value of undefined.
A regular expression the value must match. Only applies to text-like types (text, email, url, tel, password, search).
minlength
minlength has a default value of undefined.
Minimum number of characters. Only applies to text-like types.
maxlength
maxlength has a default value of undefined.
Maximum number of characters. Only applies to text-like types.
min
min has a default value of undefined.
Minimum value. For input-type="number" this is passed to
the native input. For input-type="date" it is an ISO 8601
date used for custom range validation.
max
max has a default value of undefined.
Maximum value. For input-type="number" this is passed to
the native input. For input-type="date" it is an ISO 8601
date used for custom range validation.
step
step has a default value of undefined.
Step value for input-type="number".
inputmode
inputmode has a default value of undefined.
Hint the browser about which virtual keyboard to show.
When not set, a sensible default is chosen based on
input-type (e.g. "email" for email, "numeric" for
number and date).
tel-localities
tel-localities has a default value of undefined.
Space-separated list of region codes that defines which
phone localities are accepted for input-type="tel". The
first locality whose format matches wins. When omitted,
defaults to a set of 10 common regions.
intent
intent has a default value of undefined.
The element's intent — its meaning: neutral
(no pin), or success, warning, danger, info — each pinned
to its fixed status family (blue for info), retunable per theme
via intents. On token-emitting controls a non-neutral intent pins the
filled-action pair to that family, derived over the governing
zone's theme; class-styled chrome (badges, callouts, status pills)
opts out of inline emission and renders its treatment from CSS
classes instead. An intent never repaints the surrounding zone,
which is what contexts are for. Removing the attribute restores
the element's own default intent.
context
context has a default value of undefined.
A theme-defined color zone. The selected context rebinds designer-facing roles and emits a complete, contrast-enforced semantic token table on this host for descendants to inherit.
Methods
<esp-input> has the following methods:
focus
Focus the input element.
validate
Re-run constraint validation and dispatch esp-validity-changed.
checkValidity
Check whether the current state is valid (delegates to ElementInternals).
traverseToClosest
Traverse up the DOM tree to find the closest element that matches the selector. This method is aware of shadow DOM boundaries and will traverse through them to find the element.
Events
<esp-input> emits the following events:
esp-value-changed
esp-value-changed is of type CustomEvent<string>.
Emitted when the input value changes.
esp-validity-changed
esp-validity-changed is of type CustomEvent<{ valid: boolean; message: string }>.
Emitted whenever constraint validation runs.
esp-input-icon-clicked
esp-input-icon-clicked is of type CustomEvent.
Emitted when the icon action button is clicked.
CSS Properties
<esp-input> has the following CSS properties:
--esp-field-background
Background color of the shared field shell. Defaults to var(--esp-color-layer-2).
--esp-field-border-color
Border color of the shared field shell. Defaults to var(--esp-color-border).
--esp-field-border-width
Border width of the shared field shell. Defaults to 1px.
--esp-field-text-color
Text color used inside the shared field shell. Defaults to var(--esp-color-text).
--esp-field-hover-bg
Hover background color of the shared field shell. Derived from --esp-field-background.
--esp-field-focus-bg
Focus background color of the shared field shell. Derived from --esp-field-background.
--esp-field-focus-shadow
Shadow color used for shared field focus treatment. Defaults to var(--esp-color-shadow).