Components

Input

A text-field component with a wrapper-owned visual surface, inline prefix/suffix addons, and invalid/disabled/readonly states. Supports light, dark, and neutral colors, default/soft/ghost styles, and three sizes through the recipe system.

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-within ring.
  • 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:

src/components/input.styleframe.ts
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:

src/components/Input.tsx
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

ColorTokenBorder (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
neutralAdaptive (light ↔ dark)The light border in light mode, the dark border in dark modeDefault color, adapts to the current color scheme
Pro tip: Use 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

SizeFont SizeMin HeightPadding (V / H)Border Radius
sm@font-size.xs2rem@0.375 / @0.625@border-radius.sm
md@font-size.sm2.25rem@0.5 / @0.75@border-radius.md
lg@font-size.md2.5rem@0.625 / @0.875@border-radius.md
Good to know: Pass the same 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.

Good to know: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.

Pro tip: Reach for 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:

PartRecipeRole
FielduseInputRecipe()The .input wrapper — owns the visual field (border, background, padding, :focus-within ring) and contains the transparent nested .input-field input
PrefixuseInputPrefixRecipe()Leading inline addon inside the field — icons, currency symbols, units
SuffixuseInputSuffixRecipe()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>
Pro tip: Use 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.focus draws around the whole field on :focus-within, in every state, invalid included (WCAG 2.4.7). The color.focus token defaults to @color.primary, so override it to change the ring of every component at once.
  • Size and touch. Each size has a min-height in 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", readonly and disabled attributes, 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 the hover-capable modifier (&: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-colors modifier, the focus ring is Highlight in forced colors mode, and a disabled field turns GrayText at full opacity. With prefers-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 via for/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-label on 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:

src/components/input.styleframe.ts
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:

src/components/input.styleframe.ts
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;
Good to know: Filtering also removes compound variants and adjusts default variants that reference filtered-out values, so your recipe stays consistent.

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:

ParameterTypeDescription
sStyleframeThe Styleframe instance
optionsDeepPartial<RecipeConfig>Optional overrides for the recipe configuration
options.baseVariantDeclarationsBlockCustom base styles for the field wrapper
options.variantsVariantsCustom variant definitions for the recipe
options.defaultVariantsRecord<keyof Variants, string>Default variant values for the recipe
options.compoundVariantsCompoundVariant[]Custom compound variant definitions for the recipe
options.filterRecord<string, string[]>Limit which variant values are generated

Variants:

VariantOptionsDefault
colorlight, dark, neutralneutral
variantdefault, soft, ghostdefault
sizesm, md, lgmd
invalidtrue, falsefalse
disabledtrue, falsefalse
readonlytrue, falsefalse

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:

VariantOptionsDefault
sizesm, md, lgmd

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:

VariantOptionsDefault
sizesm, md, lgmd

To attach interactive blocks outside the field, see the Field Group recipe.

Learn more about recipes →

Best Practices

  • Pass size consistently: Spread the same size to the wrapper and to every prefix and suffix part so the whole field scales together.
  • Pass states as booleans: The invalid, disabled, and readonly axes 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 / readonly attributes and aria-invalid in addition to the recipe state.
  • Choose the right addon kind: Use prefix/suffix for decorative or informational content inside the field, and a Field Group for interactive blocks attached to it.
  • Use neutral for 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 filter option to reduce generated CSS.
  • Override defaults at the recipe level: Set your most common combination as defaultVariants so component consumers write less code.

FAQ