@manhphi1309/list-card

A list component for displaying and grouping cards. Built using the compound component pattern.

Subcomponents

• ListCard
• ListCardGroup
• ListCardItem
• useListCardContext

Features

• Polymorphism: Full asChild support on all three components for wrapping elements like <a> or <form>.
• Context API: disabled state and variant layout styling trickles down automatically from <ListCard> and <ListCardGroup> to their children.
• Smart Spacing: <ListCard> automatically tightens its gap when it detects standalone <ListCardItem>s outside of a group.
• Flat Variant: Pass variant="flat" to the <ListCard> to remove the outer border and shadow, perfect for edge-to-edge layouts (like mobile screens).
• Compact Size: Pass size="compact" to the <ListCard> to reduce internal padding and gaps for a denser layout.
• Selected States: Pass selected to highlight an item. Customize the look with selectedVariant="background" (default) or selectedVariant="ring".
• Leading & Trailing Elements: Easily insert icons, avatars, switches, or badges into dedicated slots using leadingIcon and trailingIcon.

Dependencies

• @manhphi1309/utils
• clsx
• tailwind-merge

Installation

npm install @manhphi1309/list-card

Usage Example

import { ListCard, ListCardGroup, ListCardItem } from "@manhphi1309/list-card"

export function MyList() {
  return (
    <ListCard>
      <ListCardGroup title="Today">
        <ListCardItem>
          <div>Lunch</div>
          <div className="font-bold">$15.00</div>
        </ListCardItem>
        <ListCardItem>
          <div>Coffee</div>
          <div className="font-bold">$5.00</div>
        </ListCardItem>
      </ListCardGroup>
    </ListCard>
  )
}

Flat Layout & Standalone Items

import { ChevronRight, CreditCard } from "lucide-react"

import { ListCard, ListCardItem } from "@manhphi1309/list-card"

export function FlatList() {
  return (
    <ListCard variant="flat">
      {/* 
        Standalone items (not in a ListCardGroup) will automatically
        squish closer together and render as individual cards.
        Because variant="flat", they render edge-to-edge! 
      */}
      <ListCardItem
        leadingIcon={<CreditCard />}
        trailingIcon={<ChevronRight />}
      >
        <span>Payment Methods</span>
      </ListCardItem>
      <ListCardItem disabled>
        <span>Notifications (Disabled)</span>
      </ListCardItem>
    </ListCard>
  )
}

Selected States

import { ListCard, ListCardItem } from "@manhphi1309/list-card"

export function SelectedList() {
  return (
    <ListCard>
      <ListCardItem selected selectedVariant="background">
        <span>Selected (Background Variant)</span>
      </ListCardItem>
      <ListCardItem selected selectedVariant="ring">
        <span>Selected (Ring Variant)</span>
      </ListCardItem>
    </ListCard>
  )
}