import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import { buttonClass } from '#components/ui/button.ts';
import {
cardClass, cardHeaderClass, cardTitleClass, cardDescriptionClass,
cardActionClass, cardContentClass, cardFooterClass,
} from '#components/ui/card.ts';
import { inputClass } from '#components/ui/input.ts';
import { labelClass } from '#components/ui/label.ts';
export default function CardDemo() {
return html`
<div data-slot="card" data-size="default" class=${cn(cardClass(), 'w-full max-w-sm')}>
<div data-slot="card-header" class=${cardHeaderClass()}>
<div data-slot="card-title" class=${cardTitleClass()}>Login to your account</div>
<div data-slot="card-description" class=${cardDescriptionClass()}>
Enter your email below to login to your account
</div>
<div data-slot="card-action" class=${cardActionClass()}>
<button type="button" data-slot="button" data-variant="link" data-size="default" class=${buttonClass({ variant: 'link' })}>Sign Up</button>
</div>
</div>
<div data-slot="card-content" class=${cardContentClass()}>
<form>
<div class="flex flex-col gap-6">
<div class="grid gap-2">
<label data-slot="label" for="email" class=${labelClass()}>Email</label>
<input
data-slot="input"
id="email"
type="email"
placeholder="[email protected]"
required
class=${inputClass()}
>
</div>
<div class="grid gap-2">
<div class="flex items-center">
<label data-slot="label" for="password" class=${labelClass()}>Password</label>
<a
href="#"
class="ml-auto inline-block text-sm underline-offset-4 hover:underline"
>
Forgot your password?
</a>
</div>
<input data-slot="input" id="password" type="password" required class=${inputClass()}>
</div>
</div>
</form>
</div>
<div data-slot="card-footer" class=${cn(cardFooterClass(), 'flex-col gap-2')}>
<button type="submit" data-slot="button" data-variant="default" data-size="default" class=${cn(buttonClass(), 'w-full')}>
Login
</button>
<button type="button" data-slot="button" data-variant="outline" data-size="default" class=${cn(buttonClass({ variant: 'outline' }), 'w-full')}>
Login with Google
</button>
</div>
</div>
`;
}
View Code
Installation
Copy and paste the following code into your project.
/**
* Card: visual container. Tier-1 class helpers; compose with `<div>`
* (or any element) for each subpart.
*
* shadcn parity:
* Card (size: default | sm) → cardClass({ size })
* CardHeader → cardHeaderClass()
* CardTitle → cardTitleClass()
* CardDescription → cardDescriptionClass()
* CardAction → cardActionClass()
* CardContent → cardContentClass()
* CardFooter → cardFooterClass()
*
* Design tokens used: --card, --card-foreground, --muted-foreground, --border.
*
* A11y (required for accessible output):
* Use a REAL HEADING for `cardTitleClass()` whenever the card has a
* meaningful title. The helper only styles text, so on a `<div>` the title is
* invisible to the heading outline a screen reader user navigates by, and on a
* page of cards they get an unstructured wall. Pick the level that fits the
* surrounding document (`<h2>` under the page `<h1>`, `<h3>` inside a
* sectioned region); do not pick it for the font size, which the class sets.
* The card root is a plain `<div>` with no role, which is correct: it is a
* visual container. Give it a role only when it really is one thing, and then
* name it, e.g. `<section aria-labelledby="<the title's id">` for a landmark,
* or `role="listitem"` inside a `role="list"` for a card grid.
* A WHOLE-CARD LINK is the trap. Do not wrap the card in an `<a>` around a
* header, body, and buttons: it swallows the nested controls and gives a
* screen reader user one enormous link whose name is the entire card text.
* Put the link on the title instead and let the card be a container.
* Keep the reading order of the DOM matching the visual order.
* `cardActionClass()` places an action at the top right, but it stays after
* the title and description in the markup, which is what you want announced.
*
* @example
* ```html
* <div class=${cardClass()}>
* <div class=${cardHeaderClass()}>
* <h3 class=${cardTitleClass()}>Notifications</h3>
* <div class=${cardDescriptionClass()}>You have 3 unread messages.</div>
* <div class=${cardActionClass()}>
* <button class=${buttonClass({ variant: 'ghost', size: 'sm' })}>Mark all read</button>
* </div>
* </div>
* <div class=${cardContentClass()}>
* <p class="text-sm">Your weekly digest is ready to review.</p>
* </div>
* <div class=${cardFooterClass()}>
* <button class=${buttonClass()}>Save</button>
* </div>
* </div>
* ```
*/
export type CardSize = 'default' | 'sm';
/**
* Card root. shadcn ships `size?: "default" | "sm"` on Card across
* 14/15 style families (only new-york-v4 omits it). The class string
* uses `group/card` so the header / title / content / footer helpers
* can read the parent card's data-size and adjust their own padding
* + gap.
*
* USAGE: pass size to cardClass AND set data-size="<size>" on the
* same host element so the group-data-[size=...]/card child rules
* fire. Set `data-slot="card"` for shadcn parity.
*
* <div class=${cardClass({ size: 'sm' })} data-slot="card" data-size="sm">
* <div class=${cardHeaderClass()}>...</div>
* ...
* </div>
*
* Sizes:
* default: gap-6 / py-6 (shadcn new-york-v4 default)
* sm: gap-3 / py-3 (shadcn radix-nova + base-* defaults)
*/
export const cardClass = (opts: { size?: CardSize } = {}): string => {
const size = opts.size ?? 'default';
const base =
'rounded-xl border bg-card text-card-foreground shadow-sm [--card-spacing:--spacing(6)] data-[size=sm]:[--card-spacing:--spacing(4)] group/card flex flex-col';
return size === 'sm' ? base + ' gap-3 py-3' : base + ' gap-6 py-6';
};
/**
* Card header: supports an optional `CardAction` slot via grid layout.
* group-data-[size=sm]/card rules pick up the compact layout when the
* root card carries data-size="sm".
*/
export const cardHeaderClass = (): string =>
'grid-rows-[auto_auto] gap-2 px-6 [.border-b]:pb-6 group-data-[size=sm]/card:px-4 group-data-[size=sm]/card:gap-1 group-data-[size=sm]/card:[.border-b]:pb-3 group/card-header @container/card-header grid auto-rows-min items-start has-data-[slot=card-action]:grid-cols-[1fr_auto] has-data-[slot=card-description]:grid-rows-[auto_auto]';
/** Card title: heading text within the header. Smaller when card is data-size="sm". */
export const cardTitleClass = (): string =>
'leading-none font-semibold group-data-[size=sm]/card:text-sm';
/** Card description: subdued caption beneath the title. */
export const cardDescriptionClass = (): string => 'text-sm text-muted-foreground';
/** Card action: right-aligned controls inside the header (matches shadcn CardAction). */
export const cardActionClass = (): string =>
'col-start-2 row-span-2 row-start-1 self-start justify-self-end';
/** Card content: the main body region. Tighter padding when card is data-size="sm". */
export const cardContentClass = (): string =>
'px-6 group-data-[size=sm]/card:px-4';
/** Card footer: trailing controls or actions. Tighter padding when card is data-size="sm". */
export const cardFooterClass = (): string =>
'px-6 [.border-t]:pt-6 group-data-[size=sm]/card:px-4 group-data-[size=sm]/card:[.border-t]:pt-3 flex items-center';
Update the import paths to match your project setup.
Usage
import {
cardClass,
cardActionClass,
cardContentClass,
cardDescriptionClass,
cardFooterClass,
cardHeaderClass,
cardTitleClass,
} from '#components/ui/card.ts';
<div data-slot="card" data-size="default" class=${cardClass()}>
<div data-slot="card-header" class=${cardHeaderClass()}>
<div data-slot="card-title" class=${cardTitleClass()}>Card Title</div>
<div data-slot="card-description" class=${cardDescriptionClass()}>Card Description</div>
<div data-slot="card-action" class=${cardActionClass()}>Card Action</div>
</div>
<div data-slot="card-content" class=${cardContentClass()}>
<p>Card Content</p>
</div>
<div data-slot="card-footer" class=${cardFooterClass()}>
<p>Card Footer</p>
</div>
</div>
Composition
Use the following composition to build a card:
cardClass()
├── cardHeaderClass()
│ ├── cardTitleClass()
│ ├── cardDescriptionClass()
│ └── cardActionClass()
├── cardContentClass()
└── cardFooterClass()
Size
Pass size: 'sm' to cardClass() and set data-size="sm" on the same element to set the size of the card to small. The small size variant uses smaller spacing.
The card component supports a size prop that can be set to "sm" for a more compact appearance.
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import { buttonClass } from '#components/ui/button.ts';
import {
cardClass, cardHeaderClass, cardTitleClass, cardDescriptionClass,
cardContentClass, cardFooterClass,
} from '#components/ui/card.ts';
export default function CardSmall() {
return html`
<div data-slot="card" data-size="sm" class=${cn(cardClass({ size: 'sm' }), 'mx-auto w-full max-w-sm')}>
<div data-slot="card-header" class=${cardHeaderClass()}>
<div data-slot="card-title" class=${cardTitleClass()}>Small Card</div>
<div data-slot="card-description" class=${cardDescriptionClass()}>
This card uses the small size variant.
</div>
</div>
<div data-slot="card-content" class=${cardContentClass()}>
<p>
The card component supports a size prop that can be set to
"sm" for a more compact appearance.
</p>
</div>
<div data-slot="card-footer" class=${cardFooterClass()}>
<button type="button" data-slot="button" data-variant="outline" data-size="sm" class=${cn(buttonClass({ variant: 'outline', size: 'sm' }), 'w-full')}>
Action
</button>
</div>
</div>
`;
}
View Code
Spacing
In addition to the size option, you can use the --card-spacing CSS variable to control the spacing between sections and the inset of card parts. Every style carries it except new-york.
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import { buttonClass } from '#components/ui/button.ts';
import {
cardClass, cardHeaderClass, cardTitleClass, cardDescriptionClass,
cardActionClass, cardContentClass, cardFooterClass,
} from '#components/ui/card.ts';
import { inputClass } from '#components/ui/input.ts';
import { labelClass } from '#components/ui/label.ts';
const spacingOptions = [
{ label: '16px', value: '4' },
{ label: '20px', value: '5' },
{ label: '24px', value: '6' },
{ label: '32px', value: '8' },
];
// The toggle group reflects pressed onto the chosen item, so the card reads
// the choice with :has() and sets --card-spacing from it, with no script.
const spacingFromChoice = [
'group-has-[[value="5"][pressed]]/spacing:[--card-spacing:--spacing(5)]',
'group-has-[[value="6"][pressed]]/spacing:[--card-spacing:--spacing(6)]',
'group-has-[[value="8"][pressed]]/spacing:[--card-spacing:--spacing(8)]',
];
export default function CardSpacing() {
return html`
<div class="group/spacing mx-auto grid w-full max-w-sm gap-4">
<ui-toggle-group type="single" value="4" variant="outline" size="sm" spacing="default" class="justify-center">
${spacingOptions.map((option) => html`
<ui-toggle-group-item value=${option.value}>${option.label}</ui-toggle-group-item>
`)}
</ui-toggle-group>
<div data-slot="card" data-size="default" class=${cn(cardClass(), spacingFromChoice)}>
<div data-slot="card-header" class=${cardHeaderClass()}>
<div data-slot="card-title" class=${cardTitleClass()}>Login to your account</div>
<div data-slot="card-description" class=${cardDescriptionClass()}>
Enter your email below to login to your account
</div>
<div data-slot="card-action" class=${cardActionClass()}>
<button type="button" data-slot="button" data-variant="link" data-size="default" class=${buttonClass({ variant: 'link' })}>Sign Up</button>
</div>
</div>
<div data-slot="card-content" class=${cardContentClass()}>
<form>
<div class="flex flex-col gap-6">
<div class="grid gap-2">
<label data-slot="label" for="email-spacing" class=${labelClass()}>Email</label>
<input data-slot="input" id="email-spacing" type="email" placeholder="[email protected]" required class=${inputClass()}>
</div>
<div class="grid gap-2">
<div class="flex items-center">
<label data-slot="label" for="password-spacing" class=${labelClass()}>Password</label>
<a href="#" class="ml-auto inline-block text-sm underline-offset-4 hover:underline">
Forgot your password?
</a>
</div>
<input data-slot="input" id="password-spacing" type="password" required class=${inputClass()}>
</div>
</div>
</form>
</div>
<div data-slot="card-footer" class=${cn(cardFooterClass(), 'flex-col gap-2')}>
<button type="submit" data-slot="button" data-variant="default" data-size="default" class=${cn(buttonClass(), 'w-full')}>
Login
</button>
<button type="button" data-slot="button" data-variant="outline" data-size="default" class=${cn(buttonClass({ variant: 'outline' }), 'w-full')}>
Login with Google
</button>
</div>
</div>
</div>
`;
}
View Code
Use negative margins with -mx-(--card-spacing) to make content go edge to edge while keeping it aligned with the card inset. When the edge-to-edge content sits above a footer, use -mb-(--card-spacing) on the card content to remove the section gap.
These terms govern your use of the workspace, including access to shared documents, project files, and collaboration tools.
You are responsible for the content you upload and for ensuring that your team has the appropriate permissions to view or edit it.
We may update features or limits as the service evolves. When those changes materially affect your workflow, we will notify your workspace administrators.
By continuing, you agree to keep your account credentials secure and to follow your organization's acceptable use policies.
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import { buttonClass } from '#components/ui/button.ts';
import {
cardClass, cardHeaderClass, cardTitleClass, cardDescriptionClass,
cardContentClass, cardFooterClass,
} from '#components/ui/card.ts';
export default function CardEdgeToEdge() {
return html`
<div data-slot="card" data-size="default" class=${cn(cardClass(), 'mx-auto w-full max-w-sm')}>
<div data-slot="card-header" class=${cardHeaderClass()}>
<div data-slot="card-title" class=${cardTitleClass()}>Terms of Service</div>
<div data-slot="card-description" class=${cardDescriptionClass()}>
Review the terms before accepting the agreement.
</div>
</div>
<div data-slot="card-content" class=${cn(cardContentClass(), '-mb-(--card-spacing)')}>
<div class="-mx-(--card-spacing) max-h-48 space-y-4 overflow-y-scroll border-t bg-muted/50 px-(--card-spacing) py-4 text-sm leading-relaxed">
<p>
These terms govern your use of the workspace, including access to
shared documents, project files, and collaboration tools.
</p>
<p>
You are responsible for the content you upload and for ensuring that
your team has the appropriate permissions to view or edit it.
</p>
<p>
We may update features or limits as the service evolves. When those
changes materially affect your workflow, we will notify your
workspace administrators.
</p>
<p>
By continuing, you agree to keep your account credentials secure and
to follow your organization's acceptable use policies.
</p>
</div>
</div>
<div data-slot="card-footer" class=${cn(cardFooterClass(), 'justify-end gap-2')}>
<button type="button" data-slot="button" data-variant="outline" data-size="default" class=${buttonClass({ variant: 'outline' })}>Decline</button>
<button type="button" data-slot="button" data-variant="default" data-size="default" class=${buttonClass()}>Accept</button>
</div>
</div>
`;
}
View Code
Image
Add an image before the card header to create a card with an image.
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import { badgeClass } from '#components/ui/badge.ts';
import { buttonClass } from '#components/ui/button.ts';
import {
cardClass, cardHeaderClass, cardTitleClass, cardDescriptionClass,
cardActionClass, cardFooterClass,
} from '#components/ui/card.ts';
export default function CardImage() {
return html`
<div data-slot="card" data-size="default" class=${cn(cardClass(), 'relative mx-auto w-full max-w-sm pt-0')}>
<div class="absolute inset-0 z-30 aspect-video bg-black/35"></div>
<img
src="https://avatar.vercel.sh/shadcn1"
alt="Event cover"
class="relative z-20 aspect-video w-full object-cover brightness-60 grayscale dark:brightness-40"
>
<div data-slot="card-header" class=${cardHeaderClass()}>
<div data-slot="card-action" class=${cardActionClass()}>
<span data-slot="badge" data-variant="secondary" class=${badgeClass({ variant: 'secondary' })}>Featured</span>
</div>
<div data-slot="card-title" class=${cardTitleClass()}>Design systems meetup</div>
<div data-slot="card-description" class=${cardDescriptionClass()}>
A practical talk on component APIs, accessibility, and shipping
faster.
</div>
</div>
<div data-slot="card-footer" class=${cardFooterClass()}>
<button type="button" data-slot="button" data-variant="default" data-size="default" class=${cn(buttonClass(), 'w-full')}>View Event</button>
</div>
</div>
`;
}
View Code
RTL
To enable RTL support, see the RTL configuration guide.
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import { buttonClass } from '#components/ui/button.ts';
import {
cardClass, cardHeaderClass, cardTitleClass, cardDescriptionClass,
cardActionClass, cardContentClass, cardFooterClass,
} from '#components/ui/card.ts';
import { inputClass } from '#components/ui/input.ts';
import { labelClass } from '#components/ui/label.ts';
const translations = {
en: {
dir: 'ltr',
values: {
title: 'Login to your account',
description: 'Enter your email below to login to your account',
signUp: 'Sign Up',
email: 'Email',
emailPlaceholder: '[email protected]',
password: 'Password',
forgotPassword: 'Forgot your password?',
login: 'Login',
loginWithGoogle: 'Login with Google',
},
},
ar: {
dir: 'rtl',
values: {
title: 'تسجيل الدخول إلى حسابك',
description: 'أدخل بريدك الإلكتروني أدناه لتسجيل الدخول إلى حسابك',
signUp: 'إنشاء حساب',
email: 'البريد الإلكتروني',
emailPlaceholder: '[email protected]',
password: 'كلمة المرور',
forgotPassword: 'نسيت كلمة المرور؟',
login: 'تسجيل الدخول',
loginWithGoogle: 'تسجيل الدخول باستخدام Google',
},
},
he: {
dir: 'rtl',
values: {
title: 'התחבר לחשבון שלך',
description: 'הזן את האימייל שלך למטה כדי להתחבר לחשבון שלך',
signUp: 'הירשם',
email: 'אימייל',
emailPlaceholder: '[email protected]',
password: 'סיסמה',
forgotPassword: 'שכחת את הסיסמה?',
login: 'התחבר',
loginWithGoogle: 'התחבר עם Google',
},
},
};
// The provider is the dir attribute: every part styles itself with logical
// properties, so dir="rtl" on the card flips the whole layout.
export default function CardRtl() {
const lang = 'ar';
const { dir, values: t } = translations[lang];
return html`
<div data-slot="card" data-size="default" dir=${dir} lang=${lang} class=${cn(cardClass(), 'w-full max-w-sm')}>
<div data-slot="card-header" class=${cardHeaderClass()}>
<div data-slot="card-title" class=${cardTitleClass()}>${t.title}</div>
<div data-slot="card-description" class=${cardDescriptionClass()}>${t.description}</div>
<div data-slot="card-action" class=${cardActionClass()}>
<button type="button" data-slot="button" data-variant="link" data-size="default" class=${buttonClass({ variant: 'link' })}>${t.signUp}</button>
</div>
</div>
<div data-slot="card-content" class=${cardContentClass()}>
<form>
<div class="flex flex-col gap-6">
<div class="grid gap-2">
<label data-slot="label" for="email-rtl" class=${labelClass()}>${t.email}</label>
<input data-slot="input" id="email-rtl" type="email" placeholder=${t.emailPlaceholder} required class=${inputClass()}>
</div>
<div class="grid gap-2">
<div class="flex items-center">
<label data-slot="label" for="password-rtl" class=${labelClass()}>${t.password}</label>
<a href="#" class="ms-auto inline-block text-sm underline-offset-4 hover:underline">${t.forgotPassword}</a>
</div>
<input data-slot="input" id="password-rtl" type="password" required class=${inputClass()}>
</div>
</div>
</form>
</div>
<div data-slot="card-footer" class=${cn(cardFooterClass(), 'flex-col gap-2')}>
<button type="submit" data-slot="button" data-variant="default" data-size="default" class=${cn(buttonClass(), 'w-full')}>${t.login}</button>
<button type="button" data-slot="button" data-variant="outline" data-size="default" class=${cn(buttonClass({ variant: 'outline' }), 'w-full')}>${t.loginWithGoogle}</button>
</div>
</div>
`;
}
View Code
API Reference
Every part is a class helper you put on a native element, with the data-slot its styles key on.
cardClass
cardClass() is the root container for card content. Put it on a <div> and set data-size to the same size, which is what the parts read.
cardHeaderClass
cardHeaderClass() is used for a title, description, and optional action.
cardTitleClass
cardTitleClass() is used for the card title. Put it on a real heading when the card has a meaningful title, at the level that fits the page.
cardDescriptionClass
cardDescriptionClass() is used for helper text under the title.
cardActionClass
cardActionClass() places content in the top-right of the header (for example, a button or a badge). Keep it after the title and description in the markup, so it is announced after them.
cardContentClass
cardContentClass() is used for the main card body.
cardFooterClass
cardFooterClass() is used for actions and secondary content at the bottom of the card.
Changelog
Spacing Variable
If you added the card before your style carried the --card-spacing variable, run webjs ui diff card to see the drift, then re-add it with webjs ui add card --overwrite or apply the following updates to the class strings in components/ui/card.ts:
Update the card root spacing classes.
Replace the hard-coded gap and vertical padding with --card-spacing, and set the default and small size values on the root:
const base =
- 'group/card flex flex-col gap-4 overflow-hidden rounded-xl bg-card py-4 text-sm text-card-foreground ring-1 ring-foreground/10 has-data-[slot=card-footer]:pb-0 has-[>img:first-child]:pt-0 data-[size=sm]:gap-3 data-[size=sm]:py-3 data-[size=sm]:has-data-[slot=card-footer]:pb-0 *:[img:first-child]:rounded-t-xl *:[img:last-child]:rounded-b-xl';
+ 'group/card flex flex-col gap-(--card-spacing) overflow-hidden rounded-xl bg-card py-(--card-spacing) text-sm text-card-foreground ring-1 ring-foreground/10 [--card-spacing:--spacing(4)] has-data-[slot=card-footer]:pb-0 has-[>img:first-child]:pt-0 data-[size=sm]:[--card-spacing:--spacing(3)] data-[size=sm]:has-data-[slot=card-footer]:pb-0 *:[img:first-child]:rounded-t-xl *:[img:last-child]:rounded-b-xl';
Update the card header spacing classes.
Replace the horizontal padding and border spacing with the shared variable:
export const cardHeaderClass = (): string =>
- 'group/card-header @container/card-header grid auto-rows-min items-start gap-1 rounded-t-xl px-4 group-data-[size=sm]/card:px-3 has-data-[slot=card-action]:grid-cols-[1fr_auto] has-data-[slot=card-description]:grid-rows-[auto_auto] [.border-b]:pb-4 group-data-[size=sm]/card:[.border-b]:pb-3';
+ 'group/card-header @container/card-header grid auto-rows-min items-start gap-1 rounded-t-xl px-(--card-spacing) has-data-[slot=card-action]:grid-cols-[1fr_auto] has-data-[slot=card-description]:grid-rows-[auto_auto] [.border-b]:pb-(--card-spacing)';
Update the card content and footer spacing classes.
Use --card-spacing for the content inset and footer padding:
export const cardContentClass = (): string =>
- 'px-4 group-data-[size=sm]/card:px-3';
+ 'px-(--card-spacing)';
export const cardFooterClass = (): string =>
- 'flex items-center rounded-b-xl border-t bg-muted/50 p-4 group-data-[size=sm]/card:p-3';
+ 'flex items-center rounded-b-xl border-t bg-muted/50 p-(--card-spacing)';
After applying these changes, you can customize card spacing by setting --card-spacing on the card with an arbitrary property class:
<div data-slot="card" data-size="default" class=${cn(cardClass(), '[--card-spacing:--spacing(6)]')}>...</div>