@versini/ui-card

A flexible and accessible React card component built with TypeScript and TailwindCSS.

The Card component provides a versatile container for grouping related content with optional header and footer sections. It supports multiple themes, sizes, and accessibility features out of the box.

Table of Contents

• Features
• Installation
• Usage
• API

Features

• 🎯 Flexible Structure: Optional header, body, and footer sections
• ♿ Accessible: WCAG compliant with proper ARIA support
• 🎨 Customizable: Multiple themes, compact mode, and styling options
• 🌲 Tree-shakeable: Lightweight and optimized for bundle size
• 🔧 TypeScript: Fully typed with comprehensive prop definitions
• 🎭 Theme Support: Built-in support for light, dark, and system themes

Installation

npm install @versini/ui-card

Note: This component requires TailwindCSS and the @versini/ui-styles plugin for proper styling. See the installation documentation for complete setup instructions.

Usage

Basic Card

import { Card } from "@versini/ui-card";

function App() {
  return (
    <Card>
      <p>This is the card content.</p>
    </Card>
  );
}

Card with Header and Footer

import { Card } from "@versini/ui-card";

function App() {
  return (
    <Card header="Card Title" footer={<button>Action Button</button>}>
      <p>This is the main content of the card.</p>
    </Card>
  );
}

Card with Custom Header Component

import { Card } from "@versini/ui-card";

function App() {
  return (
    <Card
      header={
        <div className="flex justify-between items-center">
          <h3>Custom Header</h3>
          <span className="text-sm text-gray-500">Badge</span>
        </div>
      }
    >
      <p>Card content with custom header.</p>
    </Card>
  );
}

Compact Card

import { Card } from "@versini/ui-card";

function App() {
  return (
    <Card compact header="Compact Card">
      <p>This card has reduced padding for a more compact layout.</p>
    </Card>
  );
}

API

Card Props

| Prop | Type | Default | Description | | --------------- | ----------------------------------------------------------- | ---------- | ---------------------------------------------------------------------------------- | | children | React.ReactNode | - | The children to render in the card body | | header | React.ReactNode | - | The content to render in the header | | footer | React.ReactNode | - | The content to render in the footer | | mode | "darker" \| "dark" \| "light" \| "system" \| "alt-system" | "system" | The mode of Card (controls theme) | | compact | boolean | false | If true, the card will be smaller with reduced padding | | noBorder | boolean | false | Whether or not to render the Card with a border | | className | string | - | CSS class(es) to add to the main component wrapper | | bodyClassName | string | - | CSS class(es) to add to the body section | | headerClassName | string | - | CSS class(es) to add to the header section | | footerClassName | string | - | CSS class(es) to add to the footer section | | aria-labelledby | string | - | If the header prop is not provided, the Card must be described via aria-labelledby |

Examples

Different Themes

import { Card } from "@versini/ui-card";

function ThemeExamples() {
  return (
    <div className="space-y-4">
      <Card mode="light" header="Light Theme">
        Light themed card content.
      </Card>

      <Card mode="dark" header="Dark Theme">
        Dark themed card content.
      </Card>

      <Card mode="system" header="System Theme">
        System themed card that adapts to user preference.
      </Card>
    </div>
  );
}

Layout Variations

import { Card } from "@versini/ui-card";

function LayoutExamples() {
  return (
    <div className="grid grid-cols-1 md:grid-cols-2 gap-4">
      <Card header="Regular Card" footer={<button>Action</button>}>
        Standard spacing and layout.
      </Card>

      <Card compact header="Compact Card" footer={<button>Action</button>}>
        Reduced spacing for denser layouts.
      </Card>
    </div>
  );
}

Custom Styling

import { Card } from "@versini/ui-card";

function CustomStylingExamples() {
  return (
    <div className="space-y-4">
      <Card
        className="shadow-lg border-2 border-blue-200"
        headerClassName="bg-blue-50 font-bold"
        bodyClassName="bg-blue-25"
        footerClassName="bg-gray-50"
        header="Custom Styled Card"
        footer={<div className="text-right">Footer content</div>}
      >
        This card has custom styling applied to each section.
      </Card>

      <Card
        noBorder
        className="bg-gradient-to-r from-purple-50 to-pink-50"
        header="Borderless Card"
      >
        This card has no border and custom background.
      </Card>
    </div>
  );
}

Accessibility

import { Card } from "@versini/ui-card";

function AccessibilityExample() {
  return (
    <div className="space-y-4">
      {/* Card with header - automatically accessible */}
      <Card header="Accessible Card with Header">
        This card is automatically accessible because it has a header.
      </Card>

      {/* Card without header - needs aria-labelledby */}
      <Card aria-labelledby="external-heading">
        <h2 id="external-heading">External Heading</h2>
        <p>This card uses an external heading for accessibility.</p>
      </Card>
    </div>
  );
}