@phila/phila-ui-cards

Card components for displaying content in various layouts. Includes pre-built card variants and a grid layout system.

Installation

npm install @phila/phila-ui-cards
# or
yarn add @phila/phila-ui-cards
# or
pnpm add @phila/phila-ui-cards

Quick Start

<script setup lang="ts">
import { ResourceCard, CardGrid } from "@phila/phila-ui-cards";
import { faMemo } from "@fortawesome/pro-solid-svg-icons";
</script>

<template>
  <CardGrid mode="grid" minCardWidth="343px">
    <ResourceCard
      heading="Citizens Planning Institute"
      :iconProps="{ iconDefinition: faMemo }"
      href="https://www.phila.gov"
    >
      <p>Card content goes here.</p>
    </ResourceCard>
  </CardGrid>
</template>

Components

Card Variants

Pre-styled card components for common use cases.

| Component | Description | | ------------------ | -------------------------------------------------------------------------------------- | | ResourceCard | Centered content with circular icon, primary heading color, and orange icon background | | PressReleaseCard | Left-aligned content with icon for press releases and news | | MediaCard | Vertical layout with image on top, content below | | FlagCard | Horizontal/responsive layout with image, content, and call-to-action button |

Base Components

Lower-level components for building custom card layouts.

| Component | Description | | ------------- | -------------------------------------------------------------- | | BaseCard | Base card wrapper with layout system and optional link support | | CardContent | Content area with icon, heading, text, and optional button | | CardImage | Image component for cards |

Layout

| Component | Description | | ---------- | ------------------------------------------------- | | CardGrid | Grid/flexbox layout for organizing multiple cards |

Imports

Components

import {
  // Card Variants
  ResourceCard,
  PressReleaseCard,
  MediaCard,
  FlagCard,
  // Base Components
  BaseCard,
  CardContent,
  CardImage,
  // Layout
  CardGrid,
} from "@phila/phila-ui-cards";

Types

import type {
  // Base Component Types
  BaseCardProps,
  CardContentProps,
  CardImageProps,
  CardLayout,
  HeadingColor,
  // Layout Types
  CardGridProps,
  CardGridMode,
  CardGridAlign,
  // Variant Types
  ResourceCardProps,
  PressReleaseCardProps,
  MediaCardProps,
  FlagCardProps,
} from "@phila/phila-ui-cards";

Card Variant Props

ResourceCard

Centered card with circular icon background. The entire card can be a clickable link.

| Prop | Type | Default | Description | | ----------- | --------------- | ------- | ------------------------------------------------------------------ | | heading | string | - | Card title | | iconProps | BaseIconProps | - | Icon configuration (from @phila/phila-ui-core) | | href | string | - | Link destination. When provided, the entire card becomes clickable | | className | string | - | Additional CSS classes |

<ResourceCard
  heading="Citizens Planning Institute"
  :iconProps="{ iconDefinition: faMemo }"
  href="https://www.phila.gov"
>
  <p>Our newsletter keeps you up-to-date on permits, licenses, and more.</p>
</ResourceCard>

PressReleaseCard

Left-aligned card for press releases and news items.

| Prop | Type | Default | Description | | ----------- | --------------- | ------- | ---------------------- | | heading | string | - | Card title | | iconProps | BaseIconProps | - | Icon configuration | | className | string | - | Additional CSS classes |

<PressReleaseCard heading="Philadelphia Announces New Initiative" :iconProps="{ iconDefinition: faMemo }">
  <p>June 10, 2025</p>
</PressReleaseCard>

MediaCard

Vertical card with image on top.

| Prop | Type | Default | Description | | ----------- | --------------- | ------- | ---------------------- | | heading | string | - | Card title | | iconProps | BaseIconProps | - | Icon configuration | | source | string | - | Image URL | | alt | string | - | Image alt text | | className | string | - | Additional CSS classes |

<MediaCard heading="City Hall Event" source="https://example.com/image.jpg" alt="City Hall">
  <p>Event description goes here.</p>
</MediaCard>

FlagCard

Horizontal/responsive card with image, content, and button.

| Prop | Type | Default | Description | | ------------ | -------------------------------------------- | -------------- | ---------------------------------- | | heading | string | - | Card title | | iconProps | BaseIconProps | - | Icon configuration | | source | string | - | Image URL | | alt | string | - | Image alt text | | buttonText | string | - | Button label | | buttonHref | string | - | Button link destination | | layout | "horizontal" \| "vertical" \| "responsive" | "responsive" | Layout mode | | reverse | boolean | false | Reverse order of image and content | | className | string | - | Additional CSS classes |

<FlagCard
  heading="Featured Article"
  source="https://example.com/image.jpg"
  alt="Article image"
  buttonText="Read More"
  buttonHref="/article"
  layout="responsive"
>
  <p>Article summary goes here.</p>
</FlagCard>

CardGrid Props

Layout component for organizing multiple cards.

| Prop | Type | Default | Description | | -------------- | ---------------------------------- | ----------- | ----------------------------------------------------------------------------------------------- | | mode | "grid" \| "flex" | "grid" | Layout mode. grid uses CSS Grid auto-fit. flex uses flexbox where cards expand to fill rows | | minCardWidth | string | "280px" | Minimum card width before wrapping | | align | "start" \| "center" \| "stretch" | "stretch" | Vertical alignment of cards | | className | string | - | Additional CSS classes |

<!-- Grid mode: cards maintain consistent widths -->
<CardGrid mode="grid" minCardWidth="343px">
  <ResourceCard ... />
  <ResourceCard ... />
  <ResourceCard ... />
</CardGrid>

<!-- Flex mode: cards on each row expand to fill available space -->
<CardGrid mode="flex" minCardWidth="343px">
  <ResourceCard ... />
  <ResourceCard ... />
  <ResourceCard ... />
</CardGrid>

Base Component Props

BaseCard

Base wrapper component used by all card variants.

| Prop | Type | Default | Description | | ----------- | -------------------------------------------- | -------------- | ------------------------------------------------------------------------------------ | | variant | "primary" \| "secondary" | "primary" | Visual variant | | layout | "horizontal" \| "vertical" \| "responsive" | "responsive" | Layout mode for image/content arrangement | | reverse | boolean | false | Reverse order of image and content | | href | string | - | Link destination. When provided, the entire card becomes clickable with hover effect | | className | string | - | Additional CSS classes |

CardContent

Content area component with heading, icon, and optional button.

| Prop | Type | Default | Description | | -------------- | -------------------------- | ----------- | ----------------------- | | heading | string | - | Content heading | | iconProps | BaseIconProps | - | Icon configuration | | variant | "primary" \| "secondary" | "primary" | Visual variant | | centered | boolean | false | Center-align content | | headingColor | "default" \| "primary" | "default" | Heading color variant | | buttonText | string | - | Button label | | buttonHref | string | - | Button link destination | | className | string | - | Additional CSS classes |

CardImage

Image component for cards.

| Prop | Type | Default | Description | | ----------- | -------- | ------- | ---------------------- | | source | string | - | Image URL | | alt | string | - | Image alt text | | className | string | - | Additional CSS classes |

Building Custom Cards

Use the base components to create custom card layouts:

<script setup lang="ts">
import { BaseCard, CardContent, CardImage } from "@phila/phila-ui-cards";
</script>

<template>
  <BaseCard layout="horizontal" href="/my-link">
    <CardImage source="https://example.com/image.jpg" alt="Description" />
    <CardContent heading="Custom Card" headingColor="primary" centered>
      <p>Custom card content.</p>
    </CardContent>
  </BaseCard>
</template>

License

MIT