Display

Card

Name: Roy UI
Author: Dibbayajyoti Roy

Listing card with a swipeable, dot-paginated gallery.

A listing card: a gallery up top that you swipe or drag through, with pagination dots that stretch into a pill on the active slide and a long, eased slide between photos. Below it, a price line, address, hairline-divided stats, attribution footer, and a full-width action built on the Button. The gallery ships as a standalone ImageCarousel primitive too. Every surface is a CSS variable, dark theme included.

Timber-and-glass facade lit from within at dusk

Prime Pick

Image 1 of 4

$1,450,000List price

Architect-designed home · Hawthorn, Melbourne

264 m²Living4Bedrooms

Installation

Add the package to your project. The card pulls in its own CSS and the Button it renders — no global setup.

pnpm add @roy-ui/ui

Import

import { Card } from '@roy-ui/ui';

// the gallery is exported on its own, too:
import { ImageCarousel } from '@roy-ui/ui';

// or import just this component (its own 'use client' island):
import { Card } from '@roy-ui/ui/card';

Usage

Pass the listing data as props. The gallery swipes on drag and on the dots; the action at the bottom is the library Button, so it carries the same depth and press.

Default

Drag the photo or tap a dot — the track slides on a long, eased curve and the active dot stretches into a pill. Stats are separated by hairlines; the footer carries attribution.

Prime Pick

Image 1 of 4

$1,450,000List price

Architect-designed home · Hawthorn, Melbourne

264 m²Living4Bedrooms

tsx

<Card
  images={[
    { src: '/home-exterior.jpg', alt: 'Timber-and-glass facade at dusk' },
    { src: '/home-living.jpg', alt: 'Open-plan living and kitchen' },
    { src: '/home-stair.jpg', alt: 'Lounge beneath a floating staircase' },
    { src: '/home-corner.jpg', alt: 'Styled reading corner' },
  ]}
  badge="Prime Pick"
  price="$1,450,000"
  priceLabel="List price"
  subtitle="Architect-designed home · Hawthorn, Melbourne"
  stats={[
    { icon: <AreaIcon />, value: '264 m²', label: 'Living' },
    { icon: <RoomsIcon />, value: '4', label: 'Bedrooms' },
  ]}
  author="Dibbayajyoti Roy"
  authorHref="https://dibbayajyoti.com"
  authorProps={{ target: '_blank', rel: 'noreferrer' }}
  meta="2 days ago"
  onAction={() => router.push('/listings/hawthorn')}
/>

Autoplay

Set autoplay to advance the gallery on a timer — it loops back to the first photo and re-arms whenever you take over with a swipe or a dot. It pauses while you hover, and it stays still under prefers-reduced-motion. Tune the cadence with autoplayInterval (ms).

Prime Pick

Image 1 of 4

$1,450,000List price

Architect-designed home · Hawthorn, Melbourne

264 m²Living4Bedrooms

tsx

<Card
  images={images}
  autoplay
  autoplayInterval={2500}
  badge="Prime Pick"
  price="$1,450,000"
  priceLabel="List price"
  subtitle="Architect-designed home · Hawthorn, Melbourne"
  stats={stats}
  author="Dibbayajyoti Roy"
  authorHref="https://dibbayajyoti.com"
  meta="2 days ago"
/>

Just the gallery

The swipeable, dot-paginated media ships on its own as ImageCarousel. Give it a width and a ratio and drop anything into the overlay slot.

Image 1 of 4

tsx

<ImageCarousel
  images={images}
  ratio="16 / 9"
  onIndexChange={(i) => setActive(i)}
/>

Square gallery, no badge

Drop the badge by omitting it, and reshape the gallery with the ratio prop. The action keeps the card anchored even with less content above it.

Image 1 of 4

$1,450,000List price

Architect-designed home · Hawthorn, Melbourne

tsx

<Card
  images={images}
  ratio="1 / 1"
  price="$1,450,000"
  priceLabel="List price"
  subtitle="Architect-designed home · Hawthorn, Melbourne"
  author="Dibbayajyoti Roy"
  authorHref="https://dibbayajyoti.com"
  meta="2 days ago"
  actionLabel="Book a viewing"
/>

Tint the action

actionProps forwards straight onto the Button — colour, variant, loading, anything. Pass actionLabel={null} to drop the button entirely.

Prime Pick

Image 1 of 4

$1,450,000List price

Architect-designed home · Hawthorn, Melbourne

264 m²Living4Bedrooms

tsx

<Card
  images={images}
  price="$1,450,000"
  subtitle="Architect-designed home · Hawthorn, Melbourne"
  stats={stats}
  actionLabel="Request a tour"
  actionProps={{ color: '#1f6f4a' }}
/>

Light and dark

By default the card follows the system (theme="auto") — so it inherits your site's light/dark mode. The light surface is a premium off-white, not pure white, so it reads warmer and still holds an edge on a white page. Force either side with theme="light" or theme="dark".

Prime Pick

Image 1 of 4

$1,450,000List price

Architect-designed home · Hawthorn, Melbourne

264 m²Living4Bedrooms

Prime Pick

Image 1 of 4

$1,450,000List price

Architect-designed home · Hawthorn, Melbourne

264 m²Living4Bedrooms

tsx

// default — follows the system / your site theme
<Card {...listing} />

// force one side
<Card theme="light" {...listing} />
<Card theme="dark" {...listing} />

Theming

Both the card and the gallery expose their surfaces as CSS variables. Override them inline or in a stylesheet — the card already ships a prefers-color-scheme: dark theme.

Variables

.royui-card {
  --royui-card-bg: #fafaf8;            /* off-white surface */
  --royui-card-fg: #1a1a1c;            /* price + strong text */
  --royui-card-muted: rgba(0,0,0,.52); /* subtitle, author */
  --royui-card-line: rgba(0,0,0,.08);  /* hairline dividers */
  --royui-card-price-weight: 500;      /* lighter = more premium */
  --royui-card-radius: 24px;
}

.royui-carousel {
  --royui-carousel-radius: 16px;
  --royui-carousel-ratio: 4 / 3;
  --royui-carousel-dot: rgba(255,255,255,.55);
  --royui-carousel-dot-active: #ffffff;
}

Props

Unknown props spread onto the card's root <div>. The action button accepts everything Button does through actionProps.

Prop	Type	Default	Description
`images`	`CarouselImage[]`	`—`	Gallery slides. { src, alt }. One image hides the dots and drag.
`price`	`ReactNode`	`—`	Headline figure, e.g. "$1,450,000".
`priceLabel`	`ReactNode`	`—`	Muted qualifier beside the price, e.g. "List price".
`badge`	`ReactNode`	`—`	Pill over the image. Hidden when omitted.
`badgeIcon`	`ReactNode`	`gold star`	Glyph inside the badge.
`subtitle`	`ReactNode`	`—`	Secondary line — owner, address.
`stats`	`CardStat[]`	`—`	Inline { icon, label } figures, hairline-divided.
`author`	`ReactNode`	`—`	Footer attribution. Prefixed with "By".
`authorHref`	`string`	`—`	Turns the author name into a link.
`authorProps`	`AnchorHTMLAttributes`	`—`	Extra attributes for the author link — target, rel, onClick.
`meta`	`ReactNode`	`—`	Right-aligned footer note, e.g. "2 days ago".
`actionLabel`	`ReactNode`	`'View Details'`	Action button label. null drops the button.
`onAction`	`() => void`	`—`	Action button click handler.
`actionProps`	`Partial<ButtonProps>`	`—`	Forwarded onto the underlying Button.
`autoplay`	`boolean`	`false`	Auto-advance the gallery on a timer, looping. Pauses on hover.
`autoplayInterval`	`number`	`2500`	Milliseconds between auto-advances.
`ratio`	`string`	`'4 / 3'`	Aspect ratio of the gallery.
`defaultIndex`	`number`	`0`	Starting gallery slide.
`onIndexChange`	`(i: number) => void`	`—`	Fires when the gallery moves.
`hoverEffect`	`boolean`	`true`	Lift the card and zoom the photo on hover.
`theme`	`'light' \| 'dark' \| 'auto'`	`'auto'`	Follow the system (default), force off-white, or force near-black.

Card

Listing card with a swipeable, dot-paginated gallery.

import { Card } from '@roy-ui/ui'; // the gallery is exported on its own, too: import { ImageCarousel } from '@roy-ui/ui'; // or import just this component (its own 'use client' island): import { Card } from '@roy-ui/ui/card';

<Card images={[ { src: '/home-exterior.jpg', alt: 'Timber-and-glass facade at dusk' }, { src: '/home-living.jpg', alt: 'Open-plan living and kitchen' }, { src: '/home-stair.jpg', alt: 'Lounge beneath a floating staircase' }, { src: '/home-corner.jpg', alt: 'Styled reading corner' }, ]} badge="Prime Pick" price="$1,450,000" priceLabel="List price" subtitle="Architect-designed home · Hawthorn, Melbourne" stats={[ { icon: <AreaIcon />, value: '264 m²', label: 'Living' }, { icon: <RoomsIcon />, value: '4', label: 'Bedrooms' }, ]} author="Dibbayajyoti Roy" authorHref="https://dibbayajyoti.com" authorProps={{ target: '_blank', rel: 'noreferrer' }} meta="2 days ago" onAction={() => router.push('/listings/hawthorn')} />

<Card images={images} autoplay autoplayInterval={2500} badge="Prime Pick" price="$1,450,000" priceLabel="List price" subtitle="Architect-designed home · Hawthorn, Melbourne" stats={stats} author="Dibbayajyoti Roy" authorHref="https://dibbayajyoti.com" meta="2 days ago" />

<Card images={images} ratio="1 / 1" price="$1,450,000" priceLabel="List price" subtitle="Architect-designed home · Hawthorn, Melbourne" author="Dibbayajyoti Roy" authorHref="https://dibbayajyoti.com" meta="2 days ago" actionLabel="Book a viewing" />

.royui-card { --royui-card-bg: #fafaf8; /* off-white surface */ --royui-card-fg: #1a1a1c; /* price + strong text */ --royui-card-muted: rgba(0,0,0,.52); /* subtitle, author */ --royui-card-line: rgba(0,0,0,.08); /* hairline dividers */ --royui-card-price-weight: 500; /* lighter = more premium */ --royui-card-radius: 24px; } .royui-carousel { --royui-carousel-radius: 16px; --royui-carousel-ratio: 4 / 3; --royui-carousel-dot: rgba(255,255,255,.55); --royui-carousel-dot-active: #ffffff; }

Prop

Type

Default

Description

images

CarouselImage[]

—

Gallery slides. { src, alt }. One image hides the dots and drag.

price

ReactNode

—

Headline figure, e.g. "$1,450,000".

priceLabel

ReactNode

—

Muted qualifier beside the price, e.g. "List price".

badge

ReactNode

—

Pill over the image. Hidden when omitted.

badgeIcon

ReactNode

gold star

Glyph inside the badge.

subtitle

ReactNode

—

Secondary line — owner, address.

stats

CardStat[]

—

Inline { icon, label } figures, hairline-divided.

author

ReactNode

—

Footer attribution. Prefixed with "By".

authorHref

string

—

Turns the author name into a link.

authorProps

AnchorHTMLAttributes

—

Extra attributes for the author link — target, rel, onClick.

meta

ReactNode

—

Right-aligned footer note, e.g. "2 days ago".

actionLabel

ReactNode

'View Details'

Action button label. null drops the button.

onAction

() => void

—

Action button click handler.

actionProps

Partial<ButtonProps>

—

Forwarded onto the underlying Button.

autoplay

boolean

false

Auto-advance the gallery on a timer, looping. Pauses on hover.

autoplayInterval

number

2500

Milliseconds between auto-advances.

ratio

string

'4 / 3'

Aspect ratio of the gallery.

defaultIndex

number

0

Starting gallery slide.

onIndexChange

(i: number) => void

—

Fires when the gallery moves.

hoverEffect

boolean

true

Lift the card and zoom the photo on hover.

theme

'light' | 'dark' | 'auto'

'auto'

Follow the system (default), force off-white, or force near-black.