Morph

Preview

Installation

npx echo-ui-cli add morph

At a glance

Version

0.3.0

Weight

3.5 KB · 34.5 KB with what it imports · 420 B of CSS (minified and gzipped; React not counted)

Needs

hardware-button (Echo, brought with it)

Keyboard

• If focus was on a button that went away, it moves to the first new button that can take it, so a keyboard user lands on the next choice.
• Escape inside it calls onEscape.

Reduced motion

The buttons swap in place: no drawn body.

Sound

• Each cap's own press and release (HardwareButton).
• A soft pop when a neck snaps and a gulp when two caps fuse, inside a SoundProvider.

Usage

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

<Morph>
  {open ? (
    <>
      <HardwareButton onClick={keep}>Keep</HardwareButton>
      <HardwareButton variant="primary" onClick={discard}>Discard</HardwareButton>
    </>
  ) : (
    <HardwareButton onClick={() => setOpen(true)}>Close draft</HardwareButton>
  )}
</Morph>

Composition

Morph → your HardwareButtons, with echo-ui-core's MorphSurface drawn only while they change

Examples

<Morph onEscape={() => setDone(false)}>
  {done ? (
    <>
      <HardwareButton variant="primary" disabled>Done</HardwareButton>
      <HardwareButton onClick={() => setDone(false)}>Undo</HardwareButton>
    </>
  ) : (
    <HardwareButton onClick={() => setDone(true)}>Mark as done</HardwareButton>
  )}
</Morph>

<Morph>
  <HardwareButton onClick={save}>{saved ? "Saved" : "Save changes"}</HardwareButton>
</Morph>

<Morph>
  {running ? (
    <HardwareButton data-morph="30s" fill={left / total} onClick={pause}>{clock}</HardwareButton>
  ) : (
    <>
      <HardwareButton data-morph="10s" onClick={() => start(10)}>10s</HardwareButton>
      <HardwareButton data-morph="30s" onClick={() => start(30)}>30s</HardwareButton>
    </>
  )}
</Morph>

<Morph feel="cut">
  {asking ? (
    <>
      <HardwareButton onClick={no}>No</HardwareButton>
      <HardwareButton variant="primary" onClick={yes}>Yes</HardwareButton>
    </>
  ) : (
    <HardwareButton onClick={ask}>Answer</HardwareButton>
  )}
</Morph>

Accessibility

• Every cap is your own HardwareButton, with its own name, state and handlers; Morph adds none.
• If focus was on a button that went away, it moves to the first new button that can take it, so a keyboard user lands on the next choice.
• Escape inside it calls onEscape.
• Pass status to say what the new state means; it's announced politely.
• Reduced motion, forced colors and a row that wraps onto more than one line swap the buttons in place.

Motion & sound

Motion tokens

morphFeels.cell, morphFeels.mercury, morphFeels.cut

Reduced motion

The buttons swap in place: no drawn body.

Sound

Each cap's own press and release (HardwareButton).

Sound

A soft pop when a neck snaps and a gulp when two caps fuse, inside a SoundProvider.

Props

Anti-patterns

• Never divide into more than about four buttons: past that it's a menu, and Menu reads better.
• Never make a lit cap a button that does nothing — disable it and say so, as DoneButton does.
• Never make both buttons of a destructive choice primary: one lit cap is the one to press on purpose.
• Never put anything but a row of HardwareButtons inside: the body is drawn from their caps.

Changelog

• 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 · AddedSix more that change shape as you use them, all on Morph. SaveButton narrows into its own progress while your save runs, widens into a lit "Saved" and flows back. Timer opens into durations; the others run into the one you pick, which drains as the time runs and rings. Stopwatch buds a Lap button from Start, and every lap is a drop that lands in the lap count. VoiceNote records from the microphone: your voice swells the Stop button, and the take becomes a note that fills as it plays. AddToBag sends a drop from the button into the count beside it. useBudOff is that drop on its own, from any element into any other. Morph now keeps a button's identity across states when it has the same data-morph name, and draws filled caps as levels.
• v0.2.0 · 2026-10-04 · AddedThe Motion gallery's first four: your own buttons, flowing into the buttons you need next. Morph is the base. Wrap your HardwareButtons in it and render whatever state you like with plain React: when the buttons inside change, the old ones flow into the new ones as one liquid body. One becoming several pinches at the waist and comes apart; several becoming one folds; the same number move and resize in place, so a label that changes width flows to its new size. At rest there is nothing but your buttons; the body is drawn only during the change, in the cap's own material, with the labels riding on it, and it fades off the real buttons when it lands. Built on it: DoneButton ("Mark as done" becomes a lit Done and an Undo), ConfirmButton (Delete becomes Cancel and a primary Delete, then "Deleted", which flows back) and ActionFan (Share becomes its choices and a × that folds them in). Focus moves to the first new button when the one it was on goes away, Escape calls onEscape, the new state is announced, and reduced motion swaps the buttons in place. They need echo-ui-core 0.2.0, which adds the morph engine (MorphSurface, morphFeels, outline, apart) to echo-ui-core/tactile. They're live at /motion.
• v0.2.0 · 2026-10-04 · ChangedA morph's text no longer blinks out at the handover. As one set of labels gave way to the next, the new ones started a moment late, so for a frame both were faint and the button read as blank. They now start together; the words cross-fade without a gap. Everything built on Morph (DoneButton, ConfirmButton, ActionFan, SaveButton, Timer, Stopwatch, VoiceNote) gets it.
• 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 · 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 · 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 · 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.