Card Component

Description

The Card component is a flexible, accessible card layout with built-in dark mode support, keyboard navigation, split layouts, and scoped Tailwind CSS that won't interfere with your app's styles.

Installation

npm install custom-headless-card@latest

Features

• ✅ Accessible - ARIA attributes, keyboard support (Enter/Space), screen reader friendly
• ✅ Arrow key navigation - Use CardGroup to navigate between cards with arrow keys
• ✅ Built-in dark mode support with custom theme variables
• ✅ Split layout - Optional two-column layout with configurable widths
• ✅ Scoped Tailwind CSS - Won't override your app's styles
• ✅ Self-contained styling - No external CSS setup required
• ✅ Flexible customization via className and props
• ✅ Ref forwarding - Supports React.forwardRef for direct DOM access

Usage

Basic Card

import { Card } from "custom-headless-card";

const App = () => (
  <Card
    cardHeader={<span>John Doe</span>}
    cardBody={<span>Software Engineer</span>}
    cardFooter={<span>New York, NY</span>}
    onClick={() => console.log("Card clicked")}
  />
);

Card with Title and Split Layout

<Card
  cardTitle="Team Member"
  splitWidth="w-1/3"
  splitContent={<img src="/avatar.png" alt="Avatar" className="rounded-full w-16 h-16" />}
  cardHeader={<span>Jane Smith</span>}
  cardBody={<span>Product Manager</span>}
  cardFooter={<span>San Francisco, CA</span>}
/>

CardGroup with Arrow Key Navigation

Wrap multiple cards in a CardGroup to enable arrow key navigation between them:

import { Card, CardGroup } from "custom-headless-card";

const App = () => (
  <CardGroup ariaLabel="Team members" direction="horizontal">
    <Card
      cardHeader={<span>Alice</span>}
      cardBody={<span>Engineer</span>}
      tabIndex={0}
    />
    <Card
      cardHeader={<span>Bob</span>}
      cardBody={<span>Designer</span>}
      tabIndex={0}
    />
    <Card
      cardHeader={<span>Carol</span>}
      cardBody={<span>PM</span>}
      tabIndex={0}
    />
  </CardGroup>
);

Props

Card Props

| Prop | Type | Default | Description | | -------------------- | ----------------- | ----------- | --------------------------------------------------------------------------- | | cardHeader | ReactNode | - | Required. The header content of the card. | | cardBody | ReactNode | - | Required. The body content of the card. | | cardFooter | ReactNode | - | Optional footer content displayed at the bottom of the card. | | cardTitle | string | - | Optional title displayed above the card content. | | onClick | () => void | - | Click handler. Adds role="button" and cursor pointer styling. | | splitWidth | string | - | Tailwind width class for the split section (e.g., "w-1/3"). | | splitContent | ReactNode | - | Content rendered in the left/split section. | | disableHoverEffect | boolean | false | Disables the hover scale and shadow effects. | | hideBorder | boolean | false | Hides the card border ring. | | className | string | "" | Additional CSS classes applied to the card container. | | ariaLabel | string | - | Accessible label for the card (recommended for clickable cards). | | tabIndex | number | - | Sets the tab index. Use 0 to make the card focusable via Tab. | | expandable | boolean | - | Deprecated. Use disableHoverEffect instead. |

CardGroup Props

| Prop | Type | Default | Description | | ----------- | --------------------------------------------- | -------------- | --------------------------------------------------------------- | | children | ReactNode | - | Card elements to render in the group. | | className | string | "" | Additional CSS classes for the group container. | | ariaLabel | string | - | Accessible label for the card group. | | direction | "horizontal" \| "vertical" \| "both" | "horizontal" | Arrow key navigation direction. |

Navigation Directions

| Direction | Keys | | -------------- | ----------------------- | | horizontal | Left / Right arrows | | vertical | Up / Down arrows | | both | All four arrow keys |

Accessibility

The Card component supports WCAG 2.1 AA compliance:

• Keyboard activation - Enter and Space keys trigger onClick when the card is focused
• Arrow key navigation - CardGroup enables arrow key navigation between cards with wrapping
• ARIA attributes - role="button" on clickable cards, aria-label and aria-labelledby support
• Focus styles - Visible focus ring using the project's purple theme color
• Screen reader support - Proper semantic structure with headings and labels

Styles

The Card component uses scoped Tailwind CSS that won't conflict with your application's styles. All Tailwind utilities are contained within the .card-scoped wrapper.

Built-in Theme Variables

The component includes custom theme variables for consistent styling:

• background-dark (#212529) - Dark mode background
• background (#f8f7f4) - Light mode background
• purple (#7286d3) - Focus ring and outline color
• button-approve-dark (#93a6e2) - Dark mode focus ring color

Dark Mode Support

The component automatically adapts to dark mode when the dark class is present on a parent element:

<body className="dark">
  <App />
</body>

No Setup Required

The Card component is completely self-contained:

• ✅ No external CSS imports needed
• ✅ Won't override your app's Tailwind setup
• ✅ Works independently of your project's CSS configuration