Layer card

Group related content in a quiet inset card.

Preview

Have an existing project?

Create project

Design guidance

Use LayerCard when one task needs a primary panel and a related secondary action. The caller owns headings, labels, fields, status, and actions; LayerCard owns containment and surfaces. Normal (variant="basic") is borderless. Compact keeps one outer border. variant controls outer containment, secondaryPlacement controls reading and focus order, and primarySurface selects the paired surface hierarchy.

Keep a descriptive accessible name on the root when the content has no visible group heading. Use canonical Button and Field owners. The secondary part adds no interaction of its own.

Installation

Install

npx shadcn@latest add https://ghost-ui.com/r/layer-card.json

LayerCard's registry entry includes its required source dependencies. A copied Create project composition also needs the field, input, button, and dialog registry items.

Basic usage

1234567891011121314151617181920212223242526import { useState } from "react";
import { LayerCard } from "@/components/ui/layer-card";
import { Field } from "@/components/ui/field";
import { Input } from "@/components/ui/input";
import { Button } from "@/components/ui/button";

export function CreateProject({ onCreate, onImport }: {
  onCreate: (name: string) => void;
  onImport: () => void;
}) {
  const [name, setName] = useState("Website redesign");
  return <LayerCard variant="basic" secondaryPlacement="top" aria-label="Create project">
    <LayerCard.Primary>
      <h3>Create project</h3>
      <Field.Root name="project-name">
        <Field.Label>Project name</Field.Label>
        <Input value={name} onChange={(event) => setName(event.target.value)} />
      </Field.Root>
      <Button disabled={!name.trim()} onClick={() => onCreate(name.trim())}>Create project</Button>
    </LayerCard.Primary>
    <LayerCard.Secondary>
      <span>Have an existing project?</span>
      <Button variant="ghost" onClick={onImport}>Import project</Button>
    </LayerCard.Secondary>
  </LayerCard>;
}

The example's width, heading and form spacing belong to its caller layout:

layer-card-demo.css

123456.layer-card-example { width: min(100%, 384px); }
.layer-card-create-project { display: grid; gap: var(--space-6); }
.layer-card-create-project h3 { margin: 0; font-size: var(--font-size-xl); line-height: var(--leading-tight); font-weight: var(--font-weight-semibold); }
.layer-card-create-project form, .layer-card-import-form { display: grid; gap: var(--space-6); }
.layer-card-create-project p, .layer-card-import-form p { margin: 0; }
.layer-card-import-actions { display: flex; justify-content: flex-end; gap: var(--space-2); }

Structures

Primary is the main caller-owned content. Secondary is the related caller-owned content and action area. Direct parts, including Fragment-wrapped parts, are normalized into the requested placement order.

Examples

Normal / top

Normal containment (variant="basic") places the secondary action above the primary Create project form.

Have an existing project?

Create project

Normal / bottom

Use bottom placement when the related action follows the primary task.

Create project

Have an existing project?

Compact / top

Compact containment removes the shell padding and keeps an outer border while preserving primary content spacing.

Have an existing project?

Create project

Compact / bottom

Compact and bottom placement are independent choices.

Create project

Have an existing project?

Secondary surface

Set primarySurface="secondary" when the primary panel should use the secondary surface. LayerCard pairs the outer and secondary surfaces with palette-200 in light mode and palette-700 in dark mode. This preserves the layer hierarchy; the panels never share the same surface token.

Create project

Have an existing project?

The secondaryVisible prop defaults to true. Set it to false in basic/compact to omit Secondary while keeping Primary in place. Composer uses this control for its initially hidden task or approval panel.

API reference

LayerCard properties
Prop	Type	Default	Description
`variant`	`'basic' \| 'compact' \| 'default' \| 'stacked'`	`'default'`	Selects outer containment. `default` and `stacked` remain legacy compositions.
`secondaryVisible`	`boolean`	`true`	Omits Secondary in basic/compact while preserving Primary and its draft state.
`secondaryPlacement`	`'top' \| 'bottom'`	`'top'`	Places Secondary before or after Primary in DOM, reading order, and focus order.
`primarySurface`	`'card' \| 'secondary'`	`'card'`	Pairs card with secondary, or secondary with the next lower surface (palette-200 in light, palette-700 in dark). Applies to basic/compact.
`title`	`string`		Legacy default composition title.
`description`	`string`		Legacy default composition description.
`footer`	`React.ReactNode`		Legacy default composition footer.
`children`required	`React.ReactNode`		Caller-owned content and semantic actions.

LayerCard.Primary properties
Prop	Type	Default	Description
`density`	`'default' \| 'compact'`	`'default'`	Inner content padding: 24 px or 16 px. Independent of root containment and placement.
`render`	`React.ReactElement \| render function`		Base UI render override; div by default.
`ref`	`React.Ref<HTMLDivElement>`		Forwards to the rendered primary element.

Secondary renders a div and accepts native div attributes and a ref. It has no render or density prop. Both parts accept caller-owned children and className. The root renders a section and forwards native attributes and its ref; it has no render override. Use aria-label or aria-labelledby when needed. Surfaces add no keyboard stops. secondaryPlacement and primarySurface apply to basic and compact; legacy default and stacked keep their previous composition.