Card

Card groups four presentational parts under one named export. Compose Card.Root, Card.Header, Card.Content, and Card.Footer to separate a title, body, and supporting actions. The parts do not manage selection, focus, or application state. The application owns the behavior of any controls placed inside them.

Usage

import { useId } from 'react';
import { Button } from 'twenty-ui/primitives/input';
import { Card } from 'twenty-ui/primitives/surfaces';
import { Heading, Text } from 'twenty-ui/primitives/typography';

export const ImportSummary = () => {
  const titleId = useId();

  return (
    <Card.Root fullWidth role="region" aria-labelledby={titleId}>
      <Card.Header>
        <Heading id={titleId} level={2}>
          Import summary
        </Heading>
      </Card.Header>
      <Card.Content>
        <Text>24 records are ready to import.</Text>
      </Card.Content>
      <Card.Footer>
        <Button>Review records</Button>
      </Card.Footer>
    </Card.Root>
  );
};

Use Heading at the level required by the surrounding page. Put actions in Button or a native link so keyboard and assistive-technology users can activate them.

Anatomy

Card.Root (outer surface)
├── Card.Header (optional)
├── Card.Content (optional, repeatable)
└── Card.Footer (optional)

Import Card from twenty-ui/primitives/surfaces. Card.Root supplies the outer border and clipping, but creates no sections internally. No part requires another part or a particular section order. The sections also work independently, without Card.Root or context. Each part renders a div by default and accepts native div attributes, event handlers, className, style, and a DOM ref. Use render with an element or callback to choose a semantic target. No part infers an element or role from onClick. CardRootProps, CardHeaderProps, CardContentProps, and CardFooterProps are exported from twenty-ui/primitives/surfaces, twenty-ui/primitives, and the root package.

Appearance and dividers

Card.Root has a transparent background by default. fullWidth fills its container, and backgroundColor changes the outer background. Child sections have their own backgrounds. Card.Header has a primary background, padding, and a bottom border. Card.Content has a secondary background and padding; its optional divider adds a bottom border. Card.Footer has a primary background, padding, and a top border unless divider={false}. Avoid adding two borders at the same section boundary.

import { Card } from 'twenty-ui/primitives/surfaces';
import { Text } from 'twenty-ui/primitives/typography';

export const ImportSections = () => (
  <Card.Root>
    <Card.Content divider>
      <Text>24 records are ready to import.</Text>
    </Card.Content>
    <Card.Content divider>
      <Text>3 records need review.</Text>
    </Card.Content>
    <Card.Footer divider={false}>
      <Text>Last checked just now.</Text>
    </Card.Footer>
  </Card.Root>
);

Interactive composition

Choose a native button for an action or an anchor for navigation through render. Supply target-specific attributes such as type, disabled, href, and target on that element. The actual owner supplies its keyboard, focus, disabled, and link behavior. Card does not add those behaviors to a display div.

import { Button } from 'twenty-ui/primitives/input';
import { Card } from 'twenty-ui/primitives/surfaces';
import { Text } from 'twenty-ui/primitives/typography';

type ReviewCardProps = {
  disabled?: boolean;
  onReview: () => void;
  onDismiss: () => void;
};

export const ReviewCard = ({
  disabled,
  onReview,
  onDismiss,
}: ReviewCardProps) => (
  <Card.Root>
    <Card.Content
      render={<button type="button" disabled={disabled} />}
      onClick={onReview}
    >
      <Text render={<span />}>Review 24 ready records</Text>
    </Card.Content>
    <Card.Footer>
      <Button onClick={onDismiss}>Dismiss</Button>
    </Card.Footer>
  </Card.Root>
);

The action and dismiss button are siblings inside a display card. Do not place another button, link, input, or other interactive control inside a button or link owner. When a button contains Card parts, render those parts as phrasing elements such as span.

import { Card } from 'twenty-ui/primitives/surfaces';
import { Text } from 'twenty-ui/primitives/typography';

export const ImportLinkCard = () => (
  <Card.Root render={<a href="/imports" />} fullWidth>
    <Card.Content>
      <Text>View imports</Text>
    </Card.Content>
  </Card.Root>
);

Native button and link owners retain the card layout and get a visible focus outline. Explicit button and link owners highlight on hover. Disabled owners keep their disabled appearance. Custom owners must supply their interaction behavior, including keyboard activation and disabled handling when applicable.

Independent parts and custom wrappers

A section can be used without the outer surface. Wrappers can use its exported props type and spread it to preserve native attributes, event handlers, refs, render composition, classes, and styles. With a custom target, put its target-specific ref on the supplied element. Base UI merges that ref with the part ref and composed props.

import { Card, type CardContentProps } from 'twenty-ui/primitives/surfaces';
import { Text } from 'twenty-ui/primitives/typography';

type SummaryContentProps = CardContentProps;

const SummaryContent = ({ children, ...props }: SummaryContentProps) => (
  <Card.Content {...props}>{children}</Card.Content>
);

export const StandaloneSummary = () => (
  <SummaryContent aria-label="Import summary" style={{ maxWidth: 360 }}>
    <Text>24 records are ready to import.</Text>
  </SummaryContent>
);

Migration

Replace the four separate imports with import { Card } from 'twenty-ui/primitives/surfaces'. The root package and twenty-ui/primitives also export the same Card object.

Previous API	Compound API
`Card` as a component	`Card.Root`
`CardHeader`	`Card.Header`
`CardContent`	`Card.Content`
`CardFooter`	`Card.Footer`
`ComponentProps<typeof Card>`	`ComponentProps<typeof Card.Root>`
`styled(Card)`	`styled(Card.Root)`

Apply the same member names to JSX tags, styled wrappers, and prop types. Standalone part exports are removed without compatibility aliases. Layout props, styling defaults, and independent section use remain. Replace isClickable and hasHoverHighlight with an explicit native owner through render. Move action handlers off display-only wrappers, preserve accessible names, and keep nested controls outside the primary action. Use render={<button type="button" disabled={disabled} />} for an action and render={<a href="/imports" />} for navigation. DOM refs now point to the actual rendered part.

Props

Card.Root

string

CSS background color of the outer card. Child sections have their own backgrounds.

ReactNode

Card sections or other content.

string

CSS class merged with the part class.

boolean

Sets the card width to 100% of its container.

Ref<HTMLDivElement>

Ref to the default div, or the element supplied through render.

ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>

Element or render callback composed through Base UI useRender. Supply native button or link attributes on the rendered owner.

CSSProperties

Native styles applied to the rendered part.

Card.Header

ReactNode

Header content. Supply a Heading when the title should be a semantic heading.

string

CSS class merged with the part class.

Ref<HTMLDivElement>

Ref to the default div, or the element supplied through render.

ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>

Element or render callback composed through Base UI useRender. Supply native button or link attributes on the rendered owner.

CSSProperties

Native styles applied to the rendered part.

Card.Content

ReactNode

Content displayed in the padded body.

string

CSS class merged with the part class.

boolean

Adds a bottom border.

Ref<HTMLDivElement>

Ref to the default div, or the element supplied through render.

ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>

Element or render callback composed through Base UI useRender. Supply native button or link attributes on the rendered owner.

CSSProperties

Native styles applied to the rendered part.

Card.Footer

ReactNode

Footer content, such as actions or supporting text.

string

CSS class merged with the part class.

boolean

default:"true"

Shows the top border unless explicitly set to false.

Ref<HTMLDivElement>

Ref to the default div, or the element supplied through render.

ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>

Element or render callback composed through Base UI useRender. Supply native button or link attributes on the rendered owner.

CSSProperties

Native styles applied to the rendered part.

Overview

Apps

API

Self-Host

Contribute

UI Library

Usage

Anatomy

Appearance and dividers

Interactive composition

Independent parts and custom wrappers

Migration

Props

Card.Root

Card.Header

Card.Content

Card.Footer

​Usage

​Anatomy

​Appearance and dividers

​Interactive composition

​Independent parts and custom wrappers

​Migration

​Props

​Card.Root

​Card.Header

​Card.Content

​Card.Footer

Usage

Anatomy

Appearance and dividers

Interactive composition

Independent parts and custom wrappers

Migration

Props

Card.Root

Card.Header

Card.Content

Card.Footer