Input

Overview

The Input is a text-field container used to capture single-line user input. It is composed of six 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.
• useInputGroupRecipe() — a layout coordinator for attached blocks placed outside the field, flattening the border radii at the seams.
• useInputPrependRecipe() — a transparent leading slot inside the group for buttons, selects, or other components.
• useInputAppendRecipe() — a transparent trailing slot inside the group for buttons, selects, or other components.

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.

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 and attached prepend/append slots share the same size axis, so icons, currency symbols, and buttons stay aligned with the field.
• 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

import { styleframe } from 'virtual:styleframe';
import {
    useInputRecipe,
    useInputPrefixRecipe,
    useInputSuffixRecipe,
    useInputGroupRecipe,
    useInputPrependRecipe,
    useInputAppendRecipe,
} from '@styleframe/theme';

const s = styleframe();

const input = useInputRecipe(s);
const inputPrefix = useInputPrefixRecipe(s);
const inputSuffix = useInputSuffixRecipe(s);
const inputGroup = useInputGroupRecipe(s);
const inputPrepend = useInputPrependRecipe(s);
const inputAppend = useInputAppendRecipe(s);

export default s;

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>
    );
}

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

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 primary-colored focus ring on :focus-within.

Soft

Tinted gray background with a matching border. A gentler, lower-contrast field that blends into dense forms.

Ghost

No background and no border until interaction. The field shows only the focus ring on :focus-within, making it ideal for inline editing and borderless layouts.

Sizes

Three size variants from sm to lg control the field's font size, 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

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).

Invalid

Overrides the border and the focus ring to the error color. Set it alongside aria-invalid on the native input so assistive technology hears the error.

Disabled

Dims the field to 0.5 opacity, switches the cursor to not-allowed, and blocks pointer interaction. Mirror it with the native disabled attribute so the input is also removed from the tab order.

Read-only

Applies a subtle background shift and a default cursor while keeping the value selectable. Mirror it with the native readonly attribute so the value is submitted but not editable.

Addons

Input supports two kinds of addons. Inline addons (prefix, suffix) render inside the field and share its surface — use them for icons, currency symbols, and units. Attached addons (prepend, append) render as joined blocks outside the field inside an inputGroup — use them for buttons, selects, and other components that bring their own styling.

Prefix and suffix (inline)

The prefix and suffix sit inside the wrapper, to the left and right of the caret, sharing the field's background and focus ring. They are size-aware and use a muted text color.

Prepend and append (attached)

The prepend and append are transparent slots inside an inputGroup. The group flattens the border radius at the seams where the slots meet the field, so a button or select reads as one joined control. Drop any component into the slot — its own styling takes over.

Anatomy

The Input is composed of six independent recipes. The first three build a standalone field with inline addons; the last three compose a field with attached blocks:

The nested .input-field element is the real <input>: it is transparent, has no border or padding of its own, and inherits typography and color from the wrapper. 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 with an attached button -->
<div class="inputGroup(...)">
    <span class="input(...)"><input class="input-field" /></span>
    <span class="inputAppend()"><button>Search</button></span>
</div>

Accessibility

• Pair the invalid state with aria-invalid. The error border is a visual cue only. Set aria-invalid="true" on the native input and reference an error message with aria-describedby so screen readers announce the problem.
• Mirror states on the native input. Set the real disabled and readonly attributes in addition to the recipe state, so the field is correctly removed from (or kept in) the tab order and submitted accordingly.
• Give inline addons text alternatives. A prefix or suffix that conveys meaning (a currency symbol, a unit) should be exposed to assistive technology — keep it as readable text, or add an aria-label to the input that includes it.
• 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.
• Verify contrast ratios. The dark color places light text on a dark surface. Default tokens meet WCAG AA 4.5:1 contrast. If you override colors, verify with the WebAIM Contrast Checker.

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:

Variants:

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:

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:

useInputGroupRecipe(s, options?)

Creates the input group recipe — a layout coordinator that wraps a prepend, field, and append. Paints no surface of its own; its only styling job is flattening the border radii at the seams where the slots meet the field. The size axis is exposed for prop spreading and produces no styles at the group level. Accepts the same parameters as useInputRecipe.

Variants:

useInputPrependRecipe(s, options?)

Creates the prepend recipe — a transparent leading slot inside an input group. Owns no background, border, or padding; the slotted content brings its own visual language. This recipe has no variants.

Parameters:

useInputAppendRecipe(s, options?)

Creates the append recipe — a transparent trailing slot inside an input group. Mirrors the prepend recipe. The slotted content brings its own visual language. This recipe has no variants.

Parameters:

Learn more about recipes →

Best Practices

• Pass size consistently: Spread the same size to the wrapper and to every prefix, suffix, prepend, and append 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 prepend/append 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