Inputs

Input

Baseline text field with a floating label and custom-CSS micro-motion.

A "bottom line, no base" text field for any value — email, username, password, search. A label rests over the input and lifts up-and-left on focus, an underline draws in from the left, a leading icon tints and pops, and a faint placeholder hint only appears once the label has cleared. Built-in error, success, and async-loading states bring their own micro-motion — a one-time shake on error, a stroke-drawn check on success, a trailing spinner while a live check (like username availability) is in flight. Every surface is a CSS variable, it ships light / dark / auto themes, and every animation is custom CSS that respects prefers-reduced-motion. Forwards refs and spreads every native input attribute.

Email address

We'll only use this to send your receipt.

Installation

Add the package to your project. The field ships its own CSS and draws its own icons, label motion, and underline — there's no separate stylesheet and no animation library to wire up.

pnpm add @roy-ui/ui

Import

import { Input } from '@roy-ui/ui';

// or import just this component (its own 'use client' island):
import { Input } from '@roy-ui/ui/input';

Usage

At its smallest the field is just a label. Add an icon, a helper line, a placeholder hint, or validation state as you need them — every native input attribute (type, value, onChange, required, name, autoComplete…) spreads straight onto the input, so this one component covers email, username, password, and search. The previews run dark to read against this page; the field is theme-aware either way.

Live email field

The full thing, wired up. The label lifts and recolours as you focus, the underline draws in from the left, and the @ pops as the cursor lands. Type a valid address and a check strokes in; leave a bad one and it shakes once, then turns red. Try it — focus the field and type.

Email address

We'll only use this to send your receipt.

tsx

function Field() {
  const [value, setValue] = useState('');
  const [touched, setTouched] = useState(false);
  const valid = /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value);
  const showError = touched && value.length > 0 && !valid;

  return (
    <Input
      type="email"
      label="Email address"
      icon={<AtIcon />}
      placeholder="you@company.com"
      value={value}
      onChange={(e) => setValue(e.target.value)}
      onBlur={() => setTouched(true)}
      error={showError ? 'Enter a valid email address' : false}
      success={valid}
      helperText="We'll only use this to send your receipt."
    />
  );
}

Availability check

The async use case — is this username taken? Pass loading while a live check is in flight and a spinner turns at the trailing edge; resolve it to success (green, available) or error (red, taken). This demo debounces a fake lookup; swap the timeout for a real fetch and the states are identical. Type at least three characters — try 'roy' or 'admin' for a taken name.

Username

Pick a handle — at least 3 characters.

tsx

const TAKEN = ['admin', 'roy', 'support'];

function Username() {
  const [value, setValue] = useState('');
  const [status, setStatus] = useState('idle'); // idle | checking | available | taken
  const timer = useRef();

  function onChange(next) {
    setValue(next);
    clearTimeout(timer.current);
    const handle = next.trim().toLowerCase();
    if (handle.length < 3) return setStatus('idle');
    setStatus('checking');
    timer.current = setTimeout(() => {
      setStatus(TAKEN.includes(handle) ? 'taken' : 'available');
    }, 750);
  }

  return (
    <Input
      label="Username"
      icon={<UserIcon />}
      placeholder="your_handle"
      value={value}
      onChange={(e) => onChange(e.target.value)}
      loading={status === 'checking'}
      success={status === 'available' ? `${value} is available` : false}
      error={status === 'taken' ? `${value} is already taken` : false}
      helperText={status === 'idle' ? 'Pick a handle — at least 3 characters.'
        : status === 'checking' ? 'Checking availability…' : undefined}
    />
  );
}

Password and search

Same component, different native type. Pass type="password" with a lock for a credential field, or type="search" with a magnifier — the floating label and motion are identical, only the icon and the keyboard behaviour change.

Password

At least 8 characters.

tsx

<Input type="password" label="Password" icon={<LockIcon />} />

<Input type="search" label="Search" icon={<SearchIcon />} placeholder="Search orders…" />

Just a label

No icon, no helper — the label rests flush-left over the input and floats straight up on focus. This is the whole component when you strip it back.

Full name

tsx

<Input label="Full name" />

Placeholder hint

A placeholder never collides with the label — it's held invisible until the label floats up on focus, then fades in as a faint example. Focus this field to see the hint appear.

Email address

tsx

<Input
  label="Email address"
  icon={<AtIcon />}
  placeholder="you@company.com"
/>

Error and success

Pass a string to error or success and it both recolours the field and becomes the helper line — red with a shake on entry, green with a check that draws itself in. A boolean keeps your helperText and only recolours. Error always outranks success.

Email address

Enter a valid email address

Email address

Looks good

tsx

<Input
  label="Email address"
  icon={<AtIcon />}
  defaultValue="not-an-email"
  error="Enter a valid email address"
/>

<Input
  label="Email address"
  icon={<AtIcon />}
  defaultValue="hi@royui.dev"
  success="Looks good"
/>

Disabled

The disabled attribute dims the whole field and blocks interaction — it spreads through like any other native input prop.

Email address

tsx

<Input label="Email address" icon={<AtIcon />} disabled />

Light and dark

By default the field follows the system (theme="auto"), so it inherits your site's mode. It ships its own light and dark tokens — no Tailwind, no theme provider. Force either side with theme="light" or theme="dark".

Email address

Helper text goes here

Email address

Helper text goes here

tsx

// default — follows the system / your site theme
<Input label="Email address" icon={<AtIcon />} />

// force one side
<Input theme="light" label="Email address" icon={<AtIcon />} />
<Input theme="dark" label="Email address" icon={<AtIcon />} />

Theming

The field exposes its ink, accent, line, and state colours as CSS variables. Override them inline or in a stylesheet — it already ships a prefers-color-scheme: dark theme, and theme="dark" forces it.

Variables

.royui-input {
  --royui-input-fg: #0f172a;           /* what the user types */
  --royui-input-label: #98a2b3;        /* resting label + focus hint */
  --royui-input-label-filled: #475467; /* floated, blurred, has a value */
  --royui-input-faint: #667085;        /* helper text + spinner */
  --royui-input-icon: #98a2b3;         /* leading glyph at rest */
  --royui-input-line-rest: #d0d5dd;    /* the always-there hairline */
  --royui-input-accent: #2575f0;       /* focus: label, icon, the line */
  --royui-input-error: #d92d20;
  --royui-input-success: #15a34a;
  --royui-input-font: 16px;
}

Props

label is the only required prop. Every other native input attribute — type, value, onChange, required, name, autoComplete, disabled — spreads onto the underlying <input>; className lands on the wrapper, and the ref forwards to the input.

Prop	Type	Default	Description
`label`	`string`	`—`	Required. Rests over the field and lifts on focus / when filled.
`icon`	`ReactNode`	`—`	Leading glyph in a fixed 20px slot. Greyed at rest, tints to the accent on focus.
`helperText`	`ReactNode`	`—`	Quiet line beneath the field. Replaced by an error / success string.
`placeholder`	`string`	`—`	Faint hint revealed only once the label floats up — never doubled with the label.
`error`	`boolean \| string`	`false`	Error state. A string becomes the helper line; the field shakes once and turns red.
`success`	`boolean \| string`	`false`	Success state (outranked by error). A string becomes the helper line; a check draws in.
`loading`	`boolean`	`false`	Async-pending state. Spins a glyph at the trailing edge — for live checks like availability.
`theme`	`'light' \| 'dark' \| 'auto'`	`'auto'`	Follow the system (default), or force the built-in light or dark tokens.
`disabled`	`boolean`	`false`	Native — dims the field and blocks interaction. Spreads onto the input.
`className`	`string`	`—`	Extra classes on the wrapper. Other native input attributes spread onto the input.
`ref`	`Ref<HTMLInputElement>`	`—`	Forwarded to the underlying <input>.

Input

Baseline text field with a floating label and custom-CSS micro-motion.

Usage

<Input label="Email address" icon={<AtIcon />} defaultValue="not-an-email" error="Enter a valid email address" /> <Input label="Email address" icon={<AtIcon />} defaultValue="hi@royui.dev" success="Looks good" />

// default — follows the system / your site theme <Input label="Email address" icon={<AtIcon />} /> // force one side <Input theme="light" label="Email address" icon={<AtIcon />} /> <Input theme="dark" label="Email address" icon={<AtIcon />} />

.royui-input { --royui-input-fg: #0f172a; /* what the user types */ --royui-input-label: #98a2b3; /* resting label + focus hint */ --royui-input-label-filled: #475467; /* floated, blurred, has a value */ --royui-input-faint: #667085; /* helper text + spinner */ --royui-input-icon: #98a2b3; /* leading glyph at rest */ --royui-input-line-rest: #d0d5dd; /* the always-there hairline */ --royui-input-accent: #2575f0; /* focus: label, icon, the line */ --royui-input-error: #d92d20; --royui-input-success: #15a34a; --royui-input-font: 16px; }

Prop

Type

Default

Description

label

string

—

Required. Rests over the field and lifts on focus / when filled.

icon

ReactNode

—

Leading glyph in a fixed 20px slot. Greyed at rest, tints to the accent on focus.

helperText

ReactNode

—

Quiet line beneath the field. Replaced by an error / success string.

placeholder

string

—

Faint hint revealed only once the label floats up — never doubled with the label.

error

boolean | string

false

Error state. A string becomes the helper line; the field shakes once and turns red.

success

boolean | string

false

Success state (outranked by error). A string becomes the helper line; a check draws in.

loading

boolean

false

Async-pending state. Spins a glyph at the trailing edge — for live checks like availability.

theme

'light' | 'dark' | 'auto'

'auto'

Follow the system (default), or force the built-in light or dark tokens.

disabled

boolean

false

Native — dims the field and blocks interaction. Spreads onto the input.

className

string

—

Extra classes on the wrapper. Other native input attributes spread onto the input.

ref

Ref<HTMLInputElement>

—

Forwarded to the underlying <input>.