Skip to content

Capsule Search

A small search capsule with its shortcut on it, which opens when you start searching.

import { CapsuleSearch } from '@youj/react'

Installation & usage

npm i @youj/react

For an app already set up with npx @youj/cli init, which installs the peers (@youj/core, @youj/motion, motion and Base UI) and wires the provider. New app? Start at Installation.

Use a capsule search where space is tight but search is always one key away: a toolbar, an editor's top bar, a dock. It waits as a small capsule showing its shortcut. When you press the shortcut or click it, it widens to make room to type.

import { CapsuleSearch } from '@youj/react'

<CapsuleSearch shortcut="/" placeholder="Search samples" onValueChange={setQuery} onSubmit={runSearch} />

shortcut is any single key, such as /, or mod+<key>, such as mod+k for ⌘K on Apple devices and Ctrl K elsewhere. The shortcut works from anywhere on the page, but a plain key is ignored while someone is typing in another field. width sets how wide it is at rest and when open. By default that's 11rem and 18rem, and it never grows wider than its container.

It stays open while it holds text. Once there's text, the shortcut hint becomes a clear button. Escape clears the text, and a second Escape leaves the field.

Reference

Propsvalue, defaultValue, onValueChange… (7)

Props

CapsuleSearch props
PropType
valuestring–
defaultValuestring

default ''

''
onValueChange(value: string) => void–
onSubmit(value: string) => void

Runs on Enter with the query.

–
shortcutstring

A key that focuses the field from anywhere: /, or mod+k (⌘K on Apple, Ctrl K elsewhere). Shown as a hint at rest.

–
width{ rest: string; open: string }

Its width at rest and open.

default { rest: '11rem', open: '18rem' }

{ rest: '11rem', open: '18rem' }
size'sm' | 'default'

default 'default'

'default'
Other props pass through: extends ComponentProps<'input'>.
StylingParts and data attributes

Styling

Parts: capsule-search (with data-open), capsule-search-input and capsule-search-hint.

MotionOpen and close

Motion

Motion tokens
MomentTokens
Open and closethe capsule widens with its ends kept round and its contents unstretched; a quick focus and blur reverses mid-way
spring.snappy

0.2s, bounce 0

0.2s, bounce 0

Reduced motion

It opens and closes at once.

AccessibilityARIA, announcements

Accessibility

  • It's a search box, named "Search" by default. aria-label renames it.
  • aria-keyshortcuts announces the shortcut.
  • The clear button is named by the labels' clear, which the language packs translate.