Postcard

An interactive postcard component with flip animation, front/back faces, vintage image effects, and a realistic postage stamp.

Installation

npx shadcn@latest add https://ui.collectivecreation.company/postcard.json

Preview

ARE YOU LIVING YOUR DREAMS?

Somewhere beautiful. 2024

Hello from the mountains.

The air is thin, but the view is worth it.

Alex

From:

Patagonia, Argentina

15 Jan 2024, 02:30 PM

15 Jan 2024

02:30 PM

To:

Somewhere, Earth

Usage

example.tsx

import { Postcard } from '@/components/ui/postcard'

export function MyPage() {
  return (
    <Postcard
      front={{
        imageSrc: '/my-photo.webp',
        imageAlt: 'A beautiful landscape',
        imageEffect: 'vintage',
        quote: 'EXPLORE THE WORLD',
        caption: 'Patagonia, 2024',
        captionHref: 'https://maps.google.com',
      }}
      back={{
        message: [
          'Hi there,',
          'Greetings from the edge of the world.',
        ],
        signature: 'Alex',
        senderLocation: 'Buenos Aires, Argentina',
        senderDate: '15 Jan 2024',
        senderTime: '02:30 PM',
        receiverLocation: 'Your City',
        stampSrc: '/stamp.webp',
        stampAlt: 'Postage stamp',
      }}
    />
  )
}

Composition

The postcard is composable. You can use the full Postcard wrapper or build your own layout with the sub-components.

composition.tsx

import {
  Postcard,
  PostcardFront,
  PostcardBack,
  PostcardStamp,
} from '@/components/ui/postcard'

// Using the full wrapper
<Postcard front={{...}} back={{...}} />

// Or compose manually
<div className="grid grid-cols-2 gap-4">
  <PostcardFront
    front={{
      imageSrc: '/photo.webp',
      quote: 'HELLO WORLD',
    }}
  />
  <PostcardBack
    back={{
      message: ['Hi!'],
      stampSrc: '/stamp.webp',
    }}
  />
</div>

// Standalone stamp
<PostcardStamp
  src="/stamp.webp"
  alt="Commemorative stamp"
  className="w-16"
/>

API Reference

Postcard

Prop	Type	Description
`front`	`PostcardFrontData`	Configuration for the front face
`back`	`PostcardBackData`	Configuration for the back face
`className`	`string`	Additional CSS classes
`interactive`	`boolean`	Enable click-to-flip (default: true)
`activeFace`	`front or back`	Controlled active face
`onFaceChange`	`function`	Callback when face changes

PostcardFrontData

Prop	Type	Description
`imageSrc`	`string`	Front image URL (required)
`imageAlt`	`string`	Image alt text
`imageEffect`	`none, misty, or vintage`	Image filter preset
`quote`	`string`	Overlay text on front
`caption`	`string`	Bottom caption text
`captionHref`	`string`	Caption link URL

PostcardBackData

Prop	Type	Description
`message`	`string array`	Paragraphs of the message
`signature`	`string`	Signature text
`senderLocation`	`string`	Sender location
`senderDate`	`string`	Sender date
`senderTime`	`string`	Sender time
`receiverLocation`	`string`	Receiver location
`stampSrc`	`string`	Stamp image URL
`stampAlt`	`string`	Stamp alt text

Customization

The postcard uses Tailwind CSS for styling. You can customize the appearance by passing a className to override wrapper styles, using the exported sub-components (PostcardFront, PostcardBack, PostcardStamp) for full control, or overriding CSS variables in your Tailwind config.

Accessibility

Clickable areas have role=button and keyboard support
Images include alt text support
Motion respects user preferences via prefers-reduced-motion (inherited from motion/react)