Command Pill Hero
Heading and a two-weight intro above an inverted monospace command pill with a prompt glyph and a labelled copy action, then a footnote and links to docs and the repository. Use as the default hero for a CLI or package.
How it differs. One command and one copy action: the inverted pill is the primary call to action, split by a hairline into command and copy cell, which stack when the container is narrower than 32rem.
Install
pnpm dlx shadcn@latest add @hazine/hero-command-pillAdds 1 file, 1 shadcn primitive (button), 2 Hazine items (@hazine/heading, @hazine/use-controllable-state), and 2 packages (lucide-react, class-variance-authority).
First time? Add the registry to components.json
{
"registries": {
"@hazine": "https://api.hazine.dev/r/{name}.json"
}
}Needed once per project. Items resolve each other through the @hazine namespace.
components/blocks/hero-command-pill.tsx, 259 lines
"use client"
import * as React from "react"
import { cva, type VariantProps } from "class-variance-authority"
import { ArrowRight, Check, CircleAlert, Copy, ExternalLink } from "lucide-react"
import { cn } from "@/lib/utils"
import { Button } from "@/components/ui/button"
import { Heading, type HeadingLevel } from "@/components/hazine/heading"
import { useControllableState } from "@/hooks/use-controllable-state"
export type CopyStatus = "idle" | "copied" | "failed"
export interface HeroCommandPillProps
extends Omit<React.ComponentProps<"section">, "title">,
VariantProps<typeof heroCommandPillVariants> {
title?: string
/** First clause of the intro sentence, set in the foreground colour. */
lead?: string
/** Rest of the intro sentence, muted. */
description?: string
headingLevel?: HeadingLevel
/** The shell command, without the prompt glyph. */
command?: string
/** One line under the pill. Pass null to leave it out. */
footnote?: string | null
/** Pass null to leave the docs link out. */
docsHref?: string | null
/** Pass null to leave the repository link out. */
repositoryHref?: string | null
copyStatus?: CopyStatus
defaultCopyStatus?: CopyStatus
onCopyStatusChange?: (status: CopyStatus) => void
/** Called after the command reached the clipboard. */
onCommandCopy?: (command: string) => void
}
const COPIED_RESET_MS = 2000
const heroCommandPillVariants = cva(
"mx-auto flex w-full max-w-6xl flex-col px-4 py-16 @3xl:px-6 @3xl:py-24",
{
variants: {
align: {
center: "items-center text-center",
start: "items-start text-start",
},
},
defaultVariants: {
align: "center",
},
}
)
// The pill is an inverted surface, so the button inside it takes the inverted
// focus colour, inset because the pill clips its corners.
const copyButtonClass =
"inline-flex h-11 shrink-0 cursor-pointer items-center justify-center gap-2 border-t border-primary-foreground/30 px-4 text-sm font-medium transition-colors duration-100 hover:bg-primary-foreground/10 focus-visible:outline-2 focus-visible:-outline-offset-2 focus-visible:outline-primary-foreground active:bg-primary-foreground/30 @lg:h-auto @lg:border-s @lg:border-t-0"
function selectContents(node: HTMLElement | null) {
const selection = window.getSelection()
if (!selection || !node) return
const range = document.createRange()
range.selectNodeContents(node)
selection.removeAllRanges()
selection.addRange(range)
}
export function HeroCommandPill({
title = "Preview every pull request on its own URL",
lead = "Slipway builds each branch into an isolated preview.",
description = "The link is posted on the pull request, and the preview is removed when the branch merges.",
headingLevel = 1,
command = "npx slipway@latest init",
footnote = "Needs Node 20 or later. Adds one config file to the repository.",
docsHref = "#docs",
repositoryHref = "#repository",
copyStatus: copyStatusProp,
defaultCopyStatus = "idle",
onCopyStatusChange,
onCommandCopy,
align,
className,
...props
}: HeroCommandPillProps) {
const titleId = React.useId()
const [status, setStatus] = useControllableState({
value: copyStatusProp,
defaultValue: defaultCopyStatus,
onChange: onCopyStatusChange,
})
const commandNode = React.useRef<HTMLSpanElement>(null)
const timer = React.useRef<number | null>(null)
const mounted = React.useRef(true)
const clearTimer = React.useCallback(() => {
if (timer.current === null) return
window.clearTimeout(timer.current)
timer.current = null
}, [])
React.useEffect(() => {
mounted.current = true
return () => {
mounted.current = false
clearTimer()
}
}, [clearTimer])
const copied = status === "copied"
const failed = status === "failed"
// The failure message says the command is selected, so that also has to hold
// when the status arrives through props.
React.useEffect(() => {
if (failed) selectContents(commandNode.current)
}, [failed])
async function copyCommand() {
clearTimer()
try {
await navigator.clipboard.writeText(command)
} catch {
if (!mounted.current) return
// Selected here as well: a second failed attempt does not change the status.
selectContents(commandNode.current)
setStatus("failed")
return
}
if (!mounted.current) return
setStatus("copied")
onCommandCopy?.(command)
timer.current = window.setTimeout(() => {
timer.current = null
setStatus("idle")
}, COPIED_RESET_MS)
}
const StatusIcon = copied ? Check : Copy
return (
<section
data-slot="hero-command-pill"
aria-labelledby={titleId}
className={cn("@container bg-background text-foreground", className)}
{...props}
>
<div className={heroCommandPillVariants({ align })}>
<Heading
id={titleId}
level={headingLevel}
className="max-w-3xl text-2xl font-semibold tracking-tight text-balance @lg:text-4xl"
>
{title}
</Heading>
<p className="mt-4 max-w-prose text-base leading-relaxed text-pretty text-muted-foreground">
<span className="font-medium text-foreground">{lead}</span>{" "}
{description}
</p>
<div
data-slot="hero-command-pill-command"
data-state={status}
className="mt-10 flex w-full max-w-2xl flex-col overflow-hidden rounded-lg bg-primary text-primary-foreground @lg:w-auto @lg:flex-row"
>
<code
dir="ltr"
className="flex min-w-0 flex-1 items-baseline gap-3 px-4 py-3 text-start font-mono text-sm @lg:text-base"
>
<span
aria-hidden="true"
className="font-normal select-none"
>
$
</span>
<span
ref={commandNode}
data-slot="hero-command-pill-text"
className="min-w-0 font-medium wrap-anywhere select-all"
>
{command}
</span>
</code>
<button
type="button"
data-slot="hero-command-pill-copy"
onClick={copyCommand}
className={copyButtonClass}
>
<StatusIcon aria-hidden="true" className="size-4 shrink-0" />
{/* Both labels share one grid cell, so the button keeps its width when the label changes. */}
<span className="grid">
<span
className={cn("col-start-1 row-start-1", copied && "invisible")}
>
Copy command
</span>
<span
className={cn("col-start-1 row-start-1", !copied && "invisible")}
>
Copied
</span>
</span>
</button>
</div>
<p
role="status"
data-slot="hero-command-pill-status"
className={cn(
failed
? "mt-3 flex max-w-prose items-start gap-1.5 text-start text-sm text-destructive"
: "sr-only"
)}
>
{failed && (
<CircleAlert aria-hidden="true" className="mt-1 size-3.5 shrink-0" />
)}
{copied && "Command copied to clipboard."}
{failed &&
"The clipboard is blocked on this page. The command is selected, so copy it with your keyboard shortcut."}
</p>
{footnote && !failed && (
<p className="mt-3 max-w-prose text-xs text-muted-foreground">
{footnote}
</p>
)}
{(docsHref || repositoryHref) && (
<div
className={cn(
"mt-6 flex flex-wrap items-center gap-3",
align !== "start" && "justify-center"
)}
>
{docsHref && (
<Button asChild variant="outline" size="lg">
<a href={docsHref}>
Read the docs
<ArrowRight aria-hidden="true" className="rtl:rotate-180" />
</a>
</Button>
)}
{repositoryHref && (
<Button asChild variant="ghost" size="lg">
<a href={repositoryHref}>
View the repository
<ExternalLink aria-hidden="true" />
</a>
</Button>
)}
</div>
)}
</div>
</section>
)
}
export { heroCommandPillVariants }
The demo in the preview, 31 lines
import { HeroCommandPill } from "@/components/blocks/hero-command-pill"
export default function HeroCommandPillDemo() {
return <HeroCommandPill />
}
export const scenarios = {
copied: () => <HeroCommandPill defaultCopyStatus="copied" />,
"copy-failed": () => <HeroCommandPill defaultCopyStatus="failed" />,
"start-aligned": () => (
<HeroCommandPill
align="start"
headingLevel={2}
title="Check your migrations before they reach production"
lead="Ferrule replays every pending migration against a copy of your schema."
description="It reports locks, rewrites and data loss, and exits with a status your pipeline can read."
command="pnpm dlx ferrule check"
footnote="Works with Postgres 14 to 17. Reads the connection string from your environment."
repositoryHref={null}
/>
),
overflow: () => (
<HeroCommandPill
title="Preview every pull request, every long-lived release branch and every hotfix on an isolated URL that is removed after the merge"
lead="Slipway builds each branch into an isolated preview with its own database snapshot, environment variables and background workers."
description="The link is posted on the pull request together with the build log, the bundle size against the main branch and a list of the routes that changed, and the preview is removed when the branch merges or after 14 days without a push."
command="npx slipway@latest init --template monorepo-turborepo-with-workers --region eu-central-1 --package-manager pnpm --preview-domain previews.northwind-logistics.example --skip-install"
footnote="Needs Node 20 or later and a repository with at least one commit. Adds one config file and one workflow file to the repository, and leaves existing workflows as they are."
/>
),
}
Props12
- title
- string = "Preview every pull request on its own URL"
- lead
- string = "Slipway builds each branch into an isolated preview."
- First clause of the intro sentence, set in the foreground colour.
- description
- string = "The link is posted on the pull request, and the preview is removed when the branch merges."
- Rest of the intro sentence, muted.
- headingLevel
- HeadingLevel = 1
- command
- string = "npx slipway@latest init"
- The shell command, without the prompt glyph.
- footnote
- string | null = "Needs Node 20 or later. Adds one config file to the repository."
- One line under the pill. Pass null to leave it out.
- docsHref
- string | null = "#docs"
- Pass null to leave the docs link out.
- repositoryHref
- string | null = "#repository"
- Pass null to leave the repository link out.
- copyStatus
- CopyStatus
- defaultCopyStatus
- CopyStatus = "idle"
- onCopyStatusChange
- (status: CopyStatus) => void
- onCommandCopy
- (command: string) => void
- Called after the command reached the clipboard.
Also accepts every prop of Omit<React.ComponentProps<"section">, "title"> and VariantProps<typeof heroCommandPillVariants>.
Accessibility
- Pattern
- Landmarks and headings, Button (APG, opens in a new tab)
- Keyboard
Keyboard support for Command Pill Hero Key Effect Tab Moves to the copy button, then the docs link, then the repository link Enter or Space on Copy command Copies the command and shows Copied for two seconds. If the clipboard is blocked, the command is selected and a message says so Enter on a link Follows the docs or repository link - Screen reader
Section labelled by its heading, whose level is a prop. The command is a code element read left to right with a hidden prompt glyph. Copy is a native button with a visible label, and the result is announced through a polite status region.
- Announces: Command copied to clipboard.
- Announces: The clipboard is blocked on this page. The command is selected, so copy it with your keyboard shortcut.
- Reduced motion
- No motion. Colour transitions only.
- Checked
- Not checked yet. Automated results appear here once CI has run.
Dependencies5
- button
- @hazine/heading
- @hazine/use-controllable-state
- lucide-react
- class-variance-authority
Filled chips are registry items the CLI adds for you. Outlined chips are npm packages.
Tokens shipped0
None. The item is styled by the tokens your theme already has.