Input
Overview
The Input is a text-field container used to capture single-line user input. It is composed of three recipe parts:
useInputRecipe()— the wrapper that owns the visual field: border, background, padding, and the:focus-withinring.useInputPrefixRecipe()— an inline leading addon that sits inside the field, sharing its surface.useInputSuffixRecipe()— an inline trailing addon that sits inside the field, sharing its surface.
Each composable creates a fully configured recipe with color, variant, and size options — plus compound variants on the wrapper that handle every color-variant combination and the invalid, disabled, and readonly states automatically.
To join an input with a button, select, or other bordered control as an attached block, wrap them in a Field Group rather than reaching for a built-in slot.
The Input recipes integrate directly with the default design tokens preset and generate type-safe utility classes at build time with zero runtime CSS.
Why use the Input recipe?
The Input recipe helps you:
- Ship faster with sensible defaults: Get 3 colors, 3 visual styles, 3 sizes, and three native state axes out of the box with a single set of composable calls.
- Compose rich fields: Inline prefix/suffix addons share the field's size axis, so icons, currency symbols, and units stay aligned with the text.
- Maintain consistency: Compound variants ensure every color-variant combination and every state follows the same design rules, including dark mode overrides.
- Customize without forking: Override base styles, default variants, or filter out options you don't need — all through the options API.
- Stay type-safe: Full TypeScript support means your editor catches invalid color, variant, size, or state values at compile time.
- Integrate with your tokens: Every value references the design tokens preset, so theme changes propagate automatically.
Usage
Register the recipes
Add the Input recipes to a local Styleframe instance. The global styleframe.config.ts provides design tokens and utilities, while the component-level file registers the recipes themselves:
import { styleframe } from 'virtual:styleframe';
import {
useInputRecipe,
useInputPrefixRecipe,
useInputSuffixRecipe,
} from '@styleframe/theme';
const s = styleframe();
const input = useInputRecipe(s);
const inputPrefix = useInputPrefixRecipe(s);
const inputSuffix = useInputSuffixRecipe(s);
export default s;
Build the component
Import the input, inputPrefix, and inputSuffix runtime functions from the virtual module. The wrapper paints the visual field and the nested .input-field is a transparent native <input> that inherits typography. The invalid, disabled, and readonly axes accept booleans directly:
import { input, inputPrefix, inputSuffix } from "virtual:styleframe";
interface InputProps {
color?: "light" | "dark" | "neutral";
variant?: "default" | "soft" | "ghost";
size?: "sm" | "md" | "lg";
invalid?: boolean;
disabled?: boolean;
readonly?: boolean;
prefix?: React.ReactNode;
suffix?: React.ReactNode;
}
export function Input({
color = "neutral",
variant = "default",
size = "md",
invalid = false,
disabled = false,
readonly = false,
prefix,
suffix,
...inputProps
}: InputProps & React.InputHTMLAttributes<HTMLInputElement>) {
const wrapper = input({ color, variant, size, invalid, disabled, readonly });
return (
<span className={wrapper}>
{prefix && <span className={inputPrefix({ size })}>{prefix}</span>}
<input
className="input-field"
disabled={disabled}
readOnly={readonly}
aria-invalid={invalid}
{...inputProps}
/>
{suffix && <span className={inputSuffix({ size })}>{suffix}</span>}
</span>
);
}
See it in action
Colors
The Input recipe includes 3 color variants: light, dark, and neutral. Like the Card and ChatMessage recipes, Input uses neutral-spectrum colors designed for content surfaces rather than status communication — a field's color reflects its surface, not a state. The wrapper combines each color with every visual style variant through compound variants, so you get consistent, predictable styling across all combinations — including dark mode overrides.
The neutral color adapts automatically: it uses a light appearance in light mode and a dark appearance in dark mode, making it the safest default for general-purpose forms.
Color Reference
| Color | Token | Border (hover) | Use Case |
|---|---|---|---|
light | @color.white / @color.gray-* | @color.gray-450 (@color.gray-500) | Light surfaces, stays light in dark mode |
dark | @color.gray-900 | @color.gray-500 (@color.gray-450) | Dark surfaces, stays dark in light mode |
neutral | Adaptive (light ↔ dark) | The light border in light mode, the dark border in dark mode | Default color, adapts to the current color scheme |
neutral as your default input color. It adapts to the user's color scheme automatically, so you don't need to manage light and dark variants separately.Variants
Three visual style variants control how the field surface is rendered. Each variant is combined with the selected color through compound variants, so you always get the correct background, text, and border colors for your chosen color.
Default
Opaque surface with a visible border — the standard bordered text field. Sits above the page with a solid background and reveals a focus ring in @color.focus on :focus-within. The border is at least 3:1 against the field and the page, so people can find the field before they focus it.
Soft
Tinted gray background with the same border as Default. A gentler field that sits well in dense forms.
Ghost
No background, and a bottom border in the field's border color with square bottom corners. The underline shows where the field is without boxing it in, which suits inline editing and low-chrome layouts. The focus ring appears on :focus-within.
A ghost field shows the page through it, in every color and mode. The light and dark colors keep one look in either mode, so a light ghost field keeps its dark text for a light surface and a dark ghost field keeps its light text for a dark surface. Use neutral when the field has to follow the page from one mode to the other.
Sizes
Three size variants from sm to lg control the field's font size, minimum height, padding, and border radius. The prefix and suffix addons share the same size axis, scaling their font size, inner padding, and gap to stay aligned with the field.
Size Reference
| Size | Font Size | Min Height | Padding (V / H) | Border Radius |
|---|---|---|---|---|
sm | @font-size.xs | 2rem | @0.375 / @0.625 | @border-radius.sm |
md | @font-size.sm | 2.25rem | @0.5 / @0.75 | @border-radius.md |
lg | @font-size.md | 2.5rem | @0.625 / @0.875 | @border-radius.md |
size to the wrapper and to each prefix/suffix part so the whole field scales together. The wrapper owns the radius and padding; the addons manage their own font size and gap.States
The wrapper exposes three boolean state axes that map directly to the equivalent native <input> attributes. Pass each as a boolean — the recipe also accepts the "true" / "false" string keys, but the boolean form is simpler (see Build the component).
The wrapper also reads the attributes on the nested .input-field itself: aria-invalid="true", readonly and disabled give the same look as the matching axis, through .input:has(> .input-field[aria-invalid="true"]) and its siblings. What people see then follows what assistive technologies report. The recipe never styles :invalid or :read-only, since they match a required field before anyone has typed in it.
Invalid
Draws the border in @color.error, the ghost underline included, and doubles it with a 1px inset shadow, so the field looks different without growing. The focus ring keeps @color.focus, so focus looks the same in every state. Set it alongside aria-invalid on the native input so assistive technology hears the error, and link the error message with aria-describedby.
Disabled
Dims the field to 0.5 opacity and switches the cursor to not-allowed. Forced colors mode can't show opacity, so there the border and text turn GrayText instead. Mirror it with the native disabled attribute, which blocks typing and removes the input from the tab order. If the suffix holds a clear or reveal button, disable it too, since the recipe doesn't block clicks on it.
Read-only
Switches the border to dashed and sets a default cursor while keeping the value selectable. The dashed edge tells people the value can't be changed, and the fill stays, so the value keeps its contrast on every color. A ghost field that is read-only gets a dashed underline. Mirror it with the native readonly attribute so the value is submitted but not editable.
invalid is applied before readonly and disabled in the compound variant order, so an invalid field keeps its error border even when it is also read-only, and a disabled field still dims on top of any other state.Addons
Input supports inline addons (prefix, suffix) that render inside the field and share its surface — use them for icons, currency symbols, and units. To attach an interactive block such as a button or select outside the field, group the controls with a Field Group instead.
Prefix and suffix (inline)
The prefix and suffix sit inside the wrapper, before and after the caret, sharing the field's background and focus ring. They are size-aware, and their inner padding is logical (padding-inline-end on the prefix, padding-inline-start on the suffix), so they mirror in right-to-left layouts. Their text, like the placeholder, is the field's own text color at 75%.
Attached controls (field group)
To attach a button, select, or other bordered control to the input, place them as direct children of a Field Group. The group flattens the border radius and inner border at the seams, so the controls read as one joined unit — each child keeps its own styling.
prefix/suffix when the addon is decorative or informational (an icon, a unit) and lives inside the field. Reach for a Field Group when the addon is an interactive control (a button, a dropdown) attached outside the field.Anatomy
The Input is composed of three independent recipes that build a standalone field with inline addons:
| Part | Recipe | Role |
|---|---|---|
| Field | useInputRecipe() | The .input wrapper — owns the visual field (border, background, padding, :focus-within ring) and contains the transparent nested .input-field input |
| Prefix | useInputPrefixRecipe() | Leading inline addon inside the field — icons, currency symbols, units |
| Suffix | useInputSuffixRecipe() | Trailing inline addon inside the field — icons, clear or reveal buttons |
The nested .input-field element is the real <input>: it is transparent, has no padding or visible border of its own, and inherits typography and color from the wrapper. On touch screens it gets a transparent border above and below, which makes its hit area at least 44px tall. The wrapper owns the entire visual field via :focus-within, so the focus ring appears whenever the inner input is focused.
<!-- Standalone field with inline addons -->
<span class="input(...)">
<span class="inputPrefix(...)">$</span>
<input class="input-field" />
<span class="inputSuffix(...)">.00</span>
</span>
<!-- Field attached to a button via a field group -->
<div class="fieldGroup(...)">
<span class="input(...)"><input class="input-field" /></span>
<button class="button(...)">Search</button>
</div>
useInputRecipe() on its own (with optional prefix/suffix) for most inputs, and reach for a Field Group only when you attach interactive blocks.Accessibility
The Input recipe does its part of every stylesheet rule on the Open Components Input page. Labels, error messages and autocomplete are up to the form that uses it.
- Contrast. The value has at least 4.5:1 against the field's fill, and the placeholder, prefix and suffix too: they're the field's text color at 75% (
color-mix(in srgb, currentColor 75%, transparent)), so they follow every color and mode. Every border, the ghost underline and the invalid border included, is at least 3:1 against the field and the page in light and dark mode, at rest and on hover (WCAG 1.4.3, 1.4.11). The contrast test,fieldSurfaceContrast.test.ts, checks every color × variant pair in both modes. - Focus. A 2px solid outline with a 2px offset in
@color.focusdraws around the whole field on:focus-within, in every state, invalid included (WCAG 2.4.7). Thecolor.focustoken defaults to@color.primary, so override it to change the ring of every component at once. - Size and touch. Each size has a
min-heightin rem and padding from the spacing scale, so the field grows with its text instead of clipping it. On touch screens (@media (any-pointer: coarse)), the input's text is at least 16px, so Safari on iOS doesn't zoom in on focus, and the input gets a hit area at least 44px tall (WCAG 2.5.5) without moving anything. - States. The invalid, read-only and disabled looks come from the native input's
aria-invalid="true",readonlyanddisabledattributes, or from the matching axes. Invalid shows through the border and an inset shadow, read-only through a dashed border and disabled through opacity, and none of them changes the field's size or position. - Hover. Every hover style sits behind
@media (hover: hover), through thehover-capablemodifier (&:hover-capable:hover) in the recipe, so a tap on a touch screen doesn't leave the field looking hovered. - Forced colors and more contrast. With the
forced-colorsmodifier, the focus ring isHighlightin forced colors mode, and a disabled field turnsGrayTextat full opacity. Withprefers-contrast: more, every border but the invalid one, which stays@color.error, is drawn in the field's text color at full strength. - Right to left. The field's padding is the same on both sides, and the prefix and suffix use logical padding, so the field mirrors in right-to-left layouts.
- Label every field. Associate a
<label>with the nested input viafor/id, or wrap the input in the label. The recipe styles the surface but does not provide a name. - Give inline addons text alternatives. A prefix or suffix that conveys meaning (a currency symbol, a unit) should be in the label or the hint as well. Avoid an
aria-labelon the input: it replaces the visible label as the field's name, so the name can drift from what people see and say (WCAG 2.5.3).
Customization
Overriding Defaults
Each input composable accepts an optional second argument to override any part of the recipe configuration. Overrides are deep-merged with the defaults, so you only need to specify the properties you want to change:
import { styleframe } from 'virtual:styleframe';
import { useInputRecipe } from '@styleframe/theme';
const s = styleframe();
const input = useInputRecipe(s, {
base: {
borderRadius: '@border-radius.lg',
},
defaultVariants: {
color: 'neutral',
variant: 'soft',
size: 'lg',
},
});
export default s;
Filtering Variants
If you only need a subset of the available variants, use the filter option to limit which values are generated. This reduces the output CSS and keeps your component API focused:
import { styleframe } from 'virtual:styleframe';
import { useInputRecipe } from '@styleframe/theme';
const s = styleframe();
// Only generate the neutral color with the default and soft styles
const input = useInputRecipe(s, {
filter: {
color: ['neutral'],
variant: ['default', 'soft'],
},
});
export default s;
API Reference
useInputRecipe(s, options?)
Creates the input wrapper recipe — the .input element that owns the visual field. Registers a nested .input-field selector for the transparent native input. Owns the full compound matrix: 9 color-variant combinations plus the 3 state overrides.
Parameters:
| Parameter | Type | Description |
|---|---|---|
s | Styleframe | The Styleframe instance |
options | DeepPartial<RecipeConfig> | Optional overrides for the recipe configuration |
options.base | VariantDeclarationsBlock | Custom base styles for the field wrapper |
options.variants | Variants | Custom variant definitions for the recipe |
options.defaultVariants | Record<keyof Variants, string> | Default variant values for the recipe |
options.compoundVariants | CompoundVariant[] | Custom compound variant definitions for the recipe |
options.filter | Record<string, string[]> | Limit which variant values are generated |
Variants:
| Variant | Options | Default |
|---|---|---|
color | light, dark, neutral | neutral |
variant | default, soft, ghost | default |
size | sm, md, lg | md |
invalid | true, false | false |
disabled | true, false | false |
readonly | true, false | false |
useInputPrefixRecipe(s, options?)
Creates the inline prefix recipe — a leading addon rendered inside the field, sharing its surface. Size-aware (font size, inner padding, gap) with a muted text color. Accepts the same parameters as useInputRecipe.
Variants:
| Variant | Options | Default |
|---|---|---|
size | sm, md, lg | md |
useInputSuffixRecipe(s, options?)
Creates the inline suffix recipe — a trailing addon rendered inside the field, sharing its surface. Mirrors the prefix recipe with trailing inner padding. Accepts the same parameters as useInputRecipe.
Variants:
| Variant | Options | Default |
|---|---|---|
size | sm, md, lg | md |
To attach interactive blocks outside the field, see the Field Group recipe.
Best Practices
- Pass
sizeconsistently: Spread the samesizeto the wrapper and to every prefix and suffix part so the whole field scales together. - Pass states as booleans: The
invalid,disabled, andreadonlyaxes accept a boolean directly — no"true"/"false"conversion needed (the string keys still work if you prefer them). - Mirror states on the native input: Always set the real
disabled/readonlyattributes andaria-invalidin addition to the recipe state. - Choose the right addon kind: Use
prefix/suffixfor decorative or informational content inside the field, and a Field Group for interactive blocks attached to it. - Use
neutralfor general forms: The neutral color adapts to light and dark mode automatically, making it the safest default. - Filter what you don't need: If your forms use only one color or two variants, pass a
filteroption to reduce generated CSS. - Override defaults at the recipe level: Set your most common combination as
defaultVariantsso component consumers write less code.
FAQ
.input wrapper owns the visual field — border, background, padding, and the :focus-within ring — while the nested .input-field is a transparent native <input> that inherits typography. This split lets inline prefix and suffix addons share the same surface as the typed text, and lets the focus ring respond to the inner input through :focus-within without extra JavaScript.prefix and suffix render inside the field and share its background and focus ring — use them for icons, currency symbols, and units. To attach an interactive control such as a button or select outside the field, wrap the input and the control in a Field Group, which flattens the border radii at the seams so they read as one joined unit.input({ invalid, disabled, readonly }). The recipe coerces the value to the matching "true" / "false" variant key, so the "true" / "false" strings work too — the boolean form is just simpler. Always set the matching native attribute (disabled, readonly) and aria-invalid so the field behaves correctly for keyboard and assistive-technology users.light, dark, and neutral to provide surface variations that work across all forms. Error communication is handled by the dedicated invalid state, which switches the border to the error color and adds an inset shadow.The wrapper recipe (useInputRecipe) maps each color-variant combination to specific styles. For example, when color is neutral and variant is default, the compound variant applies background: @color.white, borderColor: @color.gray-450, and color: @color.text, along with dark mode overrides. The recipe has 12 compound entries: 9 from the color × variant matrix (3 colors × 3 variants) plus 3 state overrides for invalid, readonly, and disabled.
filter option, compound variants that reference filtered-out values are automatically removed. For example, if you filter variant to only ['default', 'soft'], all compound variants matching ghost are excluded from the generated output. Default variants are also adjusted if they reference a removed value.@color.white, @border-radius.md, and @color.error through string refs. These tokens need to be defined in your Styleframe instance for the recipe to generate valid CSS. The easiest way is to use useDesignTokensPreset(s), but you can also define the required tokens manually.Field Group
A layout component for joining buttons, inputs, selects, and other bordered controls into a single unit with merged borders and shared orientation. Supports horizontal and vertical layouts plus full-width block mode through the recipe system.
Input Date
A segmented date input — a wrapper-owned field surface holding individually focusable date segments separated by muted glyphs, with light, dark, and neutral colors, default, soft, and ghost styles, three sizes, and invalid, disabled, and read-only states through the recipe system.