HardwareButton

A molded cap in a recessed well with real press travel and sound. primary/neutral/ghost; sm/md/lg on the one control scale (32/44/60px outer, so it lines up with a Field of the same size); fullWidth, icon slots, loading, engraved. It presses like a key switch (useCapPhysics), with the clicks on the mechanism; plastic color from createEchoTheme.

Feel A key switch in a recessed well: it resists, gives and clicks onto its seam, keeps sinking while you hold it, and snaps home faster than it went down, harder the longer you held.

every state →

rec

Or let the agent fetch it: get_component("hardware-button") on the Echo MCP server.

Installation

npx echo-ui-cli add hardware-button

First time? Run npx echo-ui-cli init once — it sets the project up, and add refuses to run before it.

At a glance

Version: 0.3.0
Weight: 960 B · 30.4 KB with what it imports · 2.3 KB of CSS (minified and gzipped; React not counted)
Needs: gsap, size (Echo, brought with it)
Keyboard: A native <button>, or an <a> when href is set, so focus, Enter and Space work as they always do.
Space and Enter give the same press travel and sound as a pointer.
Reduced motion: The cap does not travel, the well does not dip, the hover glint stops, and the loading dots hold still.
Sound: press as the cap lands on its seam, release as it tops out on the way home, brighter the longer it was held.

Usage

tsx

import { HardwareButton } from "@/echo/hardware-button";

<HardwareButton variant="primary" onClick={save}>
  Save
</HardwareButton>

Composition

HardwareButton

Examples

Primary record button

The one place hardware turns accent.

tsx

<HardwareButton variant="primary" onClick={record}>Record</HardwareButton>

Beside a field

The same size is the same height, so an inline form lines up.

tsx

<Field aria-label="Email" placeholder="name@example.com" />
<HardwareButton variant="primary">Invite</HardwareButton>

The screen's main action

lg for the one action a screen is built around; fullWidth to take the row.

tsx

<HardwareButton variant="primary" size="lg" fullWidth type="submit">Sign in</HardwareButton>

Icon-only, accessible

Always give icon-only buttons an aria-label.

tsx

<HardwareButton iconOnly aria-label="Play" icon={<PlayIcon />} />

The one action that matters

impact carries the press into the device. Keep it for the single action a screen is built around.

tsx

<HardwareButton variant="primary" impact onClick={record}>Record</HardwareButton>

Loading

Loading disables interaction and shows the dot pulse.

tsx

<HardwareButton loading>Saving</HardwareButton>

A cap that is a quantity

`fill` pours the primary plastic in from the start edge. Say the quantity in the label too: the fill alone isn't read aloud.

tsx

<HardwareButton fill={left / total} onClick={pause}>
  {`Pause, ${left}s left`}
</HardwareButton>

Keys that follow the typing

`held` holds a cap down from outside, with its click, as a real key goes down. It moves the cap only: it never presses the button.

tsx

<>
  {keys.map((key: string) => (
    <HardwareButton key={key} held={down.has(key)} onClick={() => type(key)}>
      {key}
    </HardwareButton>
  ))}
</>

Accessibility

A native <button>, or an <a> when href is set, so focus, Enter and Space work as they always do.
Space and Enter give the same press travel and sound as a pointer.
The click fires the moment you press, like any button: the stroke is only the picture catching up.
iconOnly has no visible text: give it an aria-label.
sm is 32px, above the 24px minimum target; on a touch screen it grows to 44px.
loading sets aria-busy and disables the button; the label stays in the accessibility tree underneath the dots.
engraved lowers the label's contrast well below AA. Use it only where the label is not the only thing saying what the button does.

Tested against WCAG 2.2 AA on every release:

axe — No axe violations, in the component's own gallery and on its page.
keyboard — Every action is reachable and operable from the keyboard alone.
focus-visible — Focus is visible on every focusable part, in normal and forced-colors mode.
forced-colors — State stays visible when the look's colours are replaced by the system's.
target-size — Every target's real hit area is at least 24×24px, at every density.
reflow — Content reflows into 320px and survives a doubled text size.

Not covered: screen-reader: not yet verified by a person. Everything above is a machine check; a person has not yet driven this component with a screen reader.

Motion & sound

Motion tokens: lift, light
Reduced motion: The cap does not travel, the well does not dip, the hover glint stops, and the loading dots hold still.
Sound: press as the cap lands on its seam, release as it tops out on the way home, brighter the longer it was held.

Props

HardwareButton props
Prop	Type	Default
`id`The element's id, so a <label for> or an aria-describedby can reach it.	`string`
`name`The field's name in a form submission, and the key react-hook-form registers.	`string`
`disabled`	`boolean`	`false`
`required`	`boolean`
`readOnly`	`boolean`
`autoFocus`Focus this control when it mounts. One per page, at most.	`boolean`
`onBlur`Fired on focus loss. react-hook-form validates onTouched and onBlur with it.	`function`
`onFocus`Fired when the control takes focus.	`function`
`onKeyDown`Keyboard handling you own — Enter to send, Escape to clear. Runs before Echo's.	`function`
`onClick`	`function`
`type`"button" (default), "submit" or "reset".	`string`
`form`The id of the form this button submits, when it sits outside it.	`string`
`value`Submitted with the form when this button is the one pressed.	`string`
`title`The browser's own hover tooltip. Never the accessible name.	`string`
`onPointerDown`Runs before Echo's own tactile handler, so the sound lands with the finger.	`function`
`onPointerUp`	`function`
`variant`primary is the lit cap for the one main action of a decision; neutral is plastic, for the rest; ghost has no cap, for a low-emphasis action (on a drawn device, its label underlined).	`"primary" \| "neutral" \| "ghost"`	`"neutral"`
`size`Outer height on the control scale, the same as a Field or Select of that size: sm 32px (toolbars, table rows, inline), md 44px (the default: forms, dialogs, a button beside a field), lg 60px (the one action a screen is built around). Defaults to the nearest SizeProvider's size.	`"sm" \| "md" \| "lg"`	`"md"`
`fullWidth`The button takes the full width of the row it's in.	`boolean`	`false`
`icon`Leading icon (a ReactNode).	`ReactNode`
`trailingIcon`Trailing icon (a ReactNode).	`ReactNode`
`iconOnly`Square cap with no text, so it needs aria-label or aria-labelledby: without one it's a type error.	`boolean`	`false`
`aria-label`The button's name when it shows no text. With iconOnly, this or aria-labelledby is required: leaving both out is a type error. A text button is named by its text.	`string`
`aria-labelledby`Id of visible text that names the button, instead of aria-label.	`string`
`loading`Shows the loading dots and stops presses, keeping the label for screen readers.	`boolean`	`false`
`engraved`Debossed label carved into the cap. Buys the carved look at a real cost: 1.13-1.87:1 on a neutral cap, ~1.05-1.3:1 on a primary one, against AA's 4.5:1. Use only where the label is not the only thing telling you what the control does. Unsupported with variant="primary", and warns in development.	`boolean`	`false`
`caption`A small machine caption under the cap. It must not repeat the label: say what the label can't, like a shortcut or a state.	`string`
`href`Renders the cap as a link (<a href>) with the same material, press and sound. Use it whenever the button navigates.	`string`
`target`With `href`: where to open the link, e.g. "_blank".	`string`
`rel`With `href`: the link relationship, e.g. "noopener".	`string`
`impact`The press lands in the whole device: the well dips with the bottom-out and a ring of light runs round it. For the one action a screen is built around, not every button.	`boolean`	`false`
`fill`How full the cap is, 0–1: the primary plastic fills it from the start edge, like a level. For a cap that is also a quantity (a timer running down, a note playing). Say the quantity in the label too.	`number`
`held`Holds the cap down from outside, with its click, the way a real key going down would; false lets it come home. For a drawn keyboard that follows the typing. It moves the cap only: it never clicks the button or sends an event.	`boolean`

Anti-patterns

Never ship an icon-only button without an aria-label — there is no accessible name otherwise.
Do not set transform on the cap or its well in CSS — useCapPhysics/GSAP owns transform; you'll fight the press.
Do not hardcode plastic colors; the cap composes var(--echo-*) so retheming works.
Engraved labels need contrast headroom — avoid on sm ghost buttons.
Don't make every button lg: it's for the one action a screen is built around. A form's buttons are md, a toolbar's sm.
Do not put impact on every button. It marks the one action a screen is built around; everywhere, it marks nothing.

Changelog

v0.3.0 · 2026-10-12 · AddedThe drawn device (echo-ui-core, echo-ui-cli, every component that draws its own material). A seed's new render setting is molded (Echo as it has always been: plastic lit by one key light) or drawn: the same parts drawn in the ink, the way a spec sheet draws a key. Every part is outlined at one weight (--echo-line, --echo-line-width), hollow on the body; a raised part stands on a hard ink edge as deep as it rises and travels down it when pressed; a recess is an outline drawn inside; something floating stands on a deeper edge. There's no light, so no gloss, no soft shadow and no glow: what a molded device lights (an LED, the rail, a readout, the focus ring, a fader's knob, a radio's pip) is solid ink, and a low-emphasis action is its label underlined. In black and white (the accent the ink) "on" is solid ink and what's drawn on it inverts: a switch's thumb turns paper, a fader's knob is knocked out with a paper ring. The primary key is the paper key that stands highest, on an ink edge twice as deep as a neutral one's, the way a spec sheet draws its CTA. The accent stays the seed's own colour as a flat fill for what's on (a chosen segment, a checked box, a slider's travel, a switch that's on), so an acid highlighter is acid, not the olive a molded device holds it to; what's drawn on it is the ink, or the body when the accent is too deep for the ink. Pressing, travel, sound, what each material is for and every contrast guarantee are unchanged. npx echo-ui-cli style set render drawn turns it on; a style sets it in its seed; the published style and config schemas describe it, and DESIGN.md says how a drawn device builds. A molded device renders exactly as before: every line is 0px wide there, and each drawn value a component reads (--echo-drawn-fill, -on-fill, -ink, -rule, -glass, -hollow, -decoration) is initial, so it falls back to what the component always drew. HardwareButton's bed is the one new hand-tuned shadow: a drawn key stands on its own edge instead of being drawn in a recess.
v0.3.0 · 2026-10-12 · ChangedEvery item needs echo-ui-core 0.3.0 (all components). The drawn device, readability past AA and the design tests live in core, and the components that use them are built against it, so each item now declares echo-ui-core >=0.3.0 <0.4.0. Update core with the items: npm install echo-ui-core@^0.3.0 (or your package manager's), then npx echo-ui-cli update. An item whose files didn't change is the same code under a new version; the 0.2.0 files stay published.
v0.2.0 · 2026-10-04 · AddedAt roundness 1, buttons and segments are pills (echo-ui-core, HardwareButton, Segmented). The theme writes --echo-cap-round (1 at radius 1, 0 below it), and a cap's and a segment's corners reach half their height when it's 1. Under 1 nothing moves: the corner is max(the molding, 0), the same pixels as before. A style whose board shows pill buttons sets radius 1; Design Eye's table says so. Before, the softest molding stopped at about 14px on a 48px cap, and a style that asked for pills couldn't get them.
v0.2.0 · 2026-10-04 · AddedThe light device (echo-ui-core, echo-ui-cli). Echo can be light: a pale chassis makes a device molded in light plastic, like a white calculator or a cream radio, and a dark one makes the device Echo has always been. There's no setting and no mode to switch; the chassis decides (devicePolarity, and values.polarity on the theme). On a light device the page is light: its ground, the well, is the body barely set in. Caps get their own ladder, a step lighter than the body with a lit rim that stops short of white, so they keep their bevel; undersides and seams are shaded darker; dim text moves toward the ground by the same step as on a dark device, and reads about 6:1 on it. Screens are paper glass printed in ink, because a glow on a pale body is a smudge. What's lit (an LED, the current rail) is still the accent, held to 3:1 on every ground, so on is brighter than off; the text it prints (a readout, a count, a current tab) and the focus ring are the accent's ink, a step deeper and held to AA, in the new accent-ink role. The primary cap is the same cap as a dark device's, the accent with a light label: its label is the new primary-cap-ink role, and progress cells, loader dots and a meter's fill, the same plastic, read 3:1 on the page. A neutral cap or a slider that fills with it under its own dark label fills with the new pour-* roles, the accent's pale stops. Shadows are drawn at half their weight, in a deep colour of the body's own hue (--echo-cast-ink) instead of black. Every guarantee holds as it does on a dark device, and the contrast sweep now runs on light bodies too. A dark seed makes exactly the theme it did before, and the new roles equal the ones they stand for there. The components that mixed a recess toward black, painted paper in the text colour or lit a pillow of light with it read the theme's new --echo-shade-ink, --echo-paper-stock and --echo-paper-ink instead, with the old value as the fallback, and a reflective screen reads --echo-screen-*; the components that print a lit label read --echo-primary-cap-ink and --echo-accent-ink the same way; every rail is drawn in the glow, and every focus ring, the ring recipes included, in the ink. style use wears a light style now, and style check says which device a style makes. A dark screen tint on a light body is still refused: one text colour can't serve both, and the theme says so.
v0.2.0 · 2026-10-04 · AddedScope: a colour per item, and softer plastic. accent gives what's inside a colour of its own for identity (a category, a filter pad, a person): the theme engine run on your colour, so its lit caps, glow and LEDs are derived and held to AA like your main accent, and every component inside picks them up. It says which one, never how it is. molding="soft" rounds the caps inside and fills them out with a pillow of light and a fuller shade; HardwareButton, QuickTile and Knob carry the pillow, and look exactly as before outside a soft Scope.
v0.2.0 · 2026-10-04 · AddedHardwareButton: held. Holds the cap down from outside, with its click, the way a real key going down would, without firing the button or sending any event. For a drawn keyboard that follows the typing; Keypad uses it for the key you type on a hardware keyboard.
v0.2.0 · 2026-10-04 · AddedHardwareButton fill. A cap can be a quantity: fill (0–1) pours the primary plastic into it from the start edge, under the label. The Timer and VoiceNote use it.
v0.2.0 · 2026-10-04 · ChangedComponents whose shadow is a recipe read it by name. 71 shadows in 54 items now say var(--echo-shadow-<name>, <the same shadow>), so they look exactly as they did (every docs page was compared before and after) and follow a theme's recipes. Scope declares the recipes that read the accent again, so a Scope's own colour still reaches its focus rings and glows, and reflective screens do the same for theirs. Shadows that move with their part (a cap's drop as it's pressed) stay in the component.
v0.2.0 · 2026-10-04 · ChangedComments only. A few source comments used screens that are no longer in the library as their example; they now make the point without them. Nothing these components render or do changes.
v0.2.0 · 2026-10-04 · ChangedBreaking: HardwareButton's sizes are the control heights, so a button lines up with a field. A button's outer height, well included, is now sm 32px, md 44px, lg 60px, the same as a Field, Select, NumberField or OtpField of that size. Before, the default button was 60px beside a 44px field, and no size of button lined up with any input, so a search bar, a filter row or an inline "invite" form never looked right.
v0.2.0 · 2026-10-04 · ChangedComments only, no behaviour change. Comments in the component source used to cite documents, milestones and ticket numbers from Echo's own planning, none of which exist in your project. The citations are gone and the sentences around them stay. Where a comment was only a citation, it now says what it meant. Three development warnings (HardwareButton's engraved/caption checks and StatusDot's missing-label check) also dropped the ticket code at the end of the message. echo-ui diff will show changes in most items; none of them are to code.
v0.2.0 · 2026-10-04 · ChangedAn item's version is now a function of declared data, not of how the changelog is formatted. The version an item ships under is published once and never rewritten, and it used to be inferred from prose: a regex for a bolded "Breaking" run across the whole unreleased section, and attribution by "does a bullet mention this name in backticks". One breaking entry therefore moved every item that changed that cycle, and an entry explaining that "Menu and Sheet are unchanged here" filed itself as a change to Menu and Sheet — which it really had.
v0.2.0 · 2026-10-04 · ChangedBreaking: every control takes a ref, an onBlur and an onFocus — and the two that were wide open are now closed. Four of 49 components could receive a ref, and onBlur appeared in zero public prop types, so react-hook-form's uncontrolled register() — which needs exactly ref, onBlur and name — could not work with any Echo control.
v0.2.0 · 2026-10-04 · ChangedThe agent brief says Echo has not shipped. llms.txt and the MCP server's instructions led with npx echo-ui-cli init, and that name on npm is a reserved stub with no executable — so a model following the brief wrote an install step that fails with npx's own error. The brief now opens with the caveat, and the docs carry it on every surface that shows a command. One switch (CLI_RELEASED) silences all of them at launch, and a test refuses to let one move without the others. Affects all components only in what the brief says about installing them; no item's props, CSS or rendered semantics change.
v0.2.0 · 2026-10-04 · ChangedEcho's home is echo-ui.com. The registry, the docs and the packages all move to it from echo.nawwara.studio. Nothing was published under the old host, so no echo.json anywhere points at it and there is nothing to migrate — this is the last release where that is true.
v0.2.0 · 2026-10-04 · ChangedControls must have an accessible name, or they don't compile. Switch, Checkbox, Slider, Segmented, Select, RadioGroup and Progress need aria-label or aria-labelledby; Field and Textarea need label, aria-label or aria-labelledby; an iconOnly HardwareButton needs aria-label or aria-labelledby. Breaking for code that left them out: add the name. A control inside a <label> points aria-labelledby at the label's text.
v0.2.0 · 2026-10-04 · ChangedWeights, line heights, letter-spacing, z-index, border widths and icon sizes come from the theme scales in all components, with the old value as a fallback, so components keep working with echo-ui-core@0.0.1. Strays moved to the nearest step: most by under a pixel; HardwareButton icons are 14/16/20px (were 15/17/19).
v0.2.0 · 2026-10-04 · FixedA light device's recesses keep the body's hue in Chromium (echo-ui-core, BUG-166). Chromium drops the hue of a colour under 0.02 chroma when it mixes in oklch, and draws the mix at hue 0, a rose. A light device's plastic is that grey, so on a lilac body every field, track and rail was pink. A mix made only of greys is made in oklab now, which has no hue to lose; a mix with an accent in it stays in oklch. On a dark device nothing you can see changes.
v0.2.0 · 2026-10-04 · FixedA primary cap's label is readable under a Scope's soft molding (BUG-147). The pillow of light across the top reached behind the tops of the label's letters and took them to 4.2:1. On the primary cap it's as bright and fades out sooner, so the label keeps the 4.5:1 the lit plastic has.
v0.2.0 · 2026-10-04 · FixedOn a phone, a tapped part no longer stays lit (BUG-143). A phone leaves what you tapped under :hover until the next tap, so a table row stayed shaded and a trigger stayed lit after the finger lifted. Hover styles now apply only where there's a pointer that can hover (@media (hover: hover)), in all 23 components that had one. Checked, active and focus styles that shared a rule with them still apply everywhere.
v0.2.0 · 2026-10-04 · FixedA component held to its container's width stays inside it, padding and all (BUG-128). HardwareButton, Badge, Tag, LcdChip, StatTile and ShortcutMap's board are capped at their container so a long label truncates or wraps, but the cap left out their own padding: a HardwareButton with href could reach 36px past a narrow column. The cap now counts the padding. A <button> cap looked right already; a link cap now matches it.
v0.2.0 · 2026-10-04 · FixedA small HardwareButton with a short label is a 44px target on a touch screen (BUG-119). It grew to 44px tall but stayed as wide as its label, so "$5" or "OK" was 40px wide. It's now at least 44px wide on a coarse pointer too.
v0.2.0 · 2026-10-04 · FixedHardwareButton no longer cuts off what's in its icon slot (BUG-114). The label's truncation rule also clipped the icon, so a digit or letter used as a key's icon lost its bottom edge, and so did any icon drawn to the edge of its box. The icon slot now centres what's in it and clips nothing; the label still truncates.
v0.2.0 · 2026-10-04 · FixedHardwareButton stays a cap when something passes it a class or a style (BUG-73). Menu's own example, <Menu.Trigger render={<HardwareButton>…</HardwareButton>} />, rendered a bare button: Base UI hands the trigger's class to the element it renders, and it replaced the cap's. A style replaced the fill the same way. Both are now added to the cap's own.
v0.2.0 · 2026-10-04 · FixedProps the docs did not list. HardwareButton (icon, trailingIcon, target, rel), Modal (trigger, title, description, footer), Popover (trigger, title), Tooltip (trigger), Slider (value, onValueChange, aria-label, aria-labelledby), NumberField (onValueChange), SoundProvider (backend) and Textured (dither, noise) now appear in the prop tables, llms-full.txt and the MCP server.
v0.2.0 · 2026-10-04 · FixedContent now reflows into a 320px screen (400% zoom) and survives a doubled browser text size (WCAG 1.4.10, 1.4.4), across all components. Select's 180px floor, NumberField's readout, Segmented and Steps as flex items, EmptyState's grid columns, and Avatar's fixed-pixel disc all gave way; Panel counts its padding inside a width you set (box-sizing: border-box), so a <Panel style={{ width: 220 }}> is now 220px wide overall rather than 260px.

Preview