Listing card

listing-card-01 is an editorial real-estate listing card. Every visible value comes from props. The card does not fetch data. Catalog access is free. The published component is MIT, Copyright (c) 2026 ShadcnEstate.

Live previewCopy Anchor Link

The live preview is the marketing route /blocks/listing-card-01.

InstallationCopy Anchor Link

pnpm dlx shadcn@latest add shadcnestate/registry/listing-card-01

The component declares no npm dependencies and no registry dependencies. The host must provide React >=18.2 <20 and Tailwind CSS >=4. It is a server-capable function component and has no client directive.

Tailwind CSS 4 generates utilities only from scanned sources. If the component directory is outside that scan, point @source at it from the host stylesheet. The path below is a host path, not an install location. The component does not ship its own CSS file.

@source "../components/listing-card-01";

UsageCopy Anchor Link

Import ListingCard from the local component entry. The specifier below is that local entry, not a published package name.

import { ListingCard } from "./listing-card-01";

export function ListingPreview() {
	return (
		<ListingCard
			title="Courtyard loft"
			image={{
				src: "/photos/courtyard.jpg",
				alt: "Courtyard",
				width: 800,
				height: 600,
			}}
			location={{ formattedLocation: "Mitte, Berlin" }}
			price={{
				amount: "1999.50",
				currency: "EUR",
				locale: "de-DE",
				period: "month",
			}}
			labels={{ periods: { month: "per month" } }}
			propertyType={{ label: "Apartment", code: "apartment" }}
			features={[
				{ id: "rooms", label: "Rooms", value: "3" },
				{ id: "area", label: "Living area", value: "92 m²" },
			]}
			href="/listings/courtyard-loft"
		/>
	);
}

Omitting state selects the ready variant, and omitting headingLevel renders an h2. The price line is the runtime currency format of 1999.50 EUR for de-DE, followed by per month. The href wraps the whole card because no cta is set.

A loading card accepts only shared props:

<ListingCard state="loading" labels={{ loading: "Loading listing" }} />

PropsCopy Anchor Link

ListingCardProps is ListingCardReadyProps when state is omitted or "ready", and ListingCardLoadingProps when state is "loading".

SharedCopy Anchor Link

ReadyCopy Anchor Link

Empty or whitespace-only titles throw ListingCard requires a non-empty title.

cta wins even when its URL is unsafe or its label is blank. A rejected call to action does not fall back to href. With neither a usable call to action nor a safe href, the card is not a link. A safe href without cta wraps the image and the details; that link has no separate label.

Safe targets are http, https, and relative URLs that pass the card's checks. Unsafe schemes, protocol-relative URLs, backslashes, and values that contain control characters or whitespace are not rendered. Encoded spaces in an otherwise safe URL are preserved. The same check applies to image src.

ListingCardImageCopy Anchor Link

ListingCardLocationCopy Anchor Link

Structured parts are joined in that order with a comma and a space. An empty location is omitted.

ListingCardPriceCopy Anchor Link

Invalid or missing prices show priceFallback when that text is non-blank, and otherwise show nothing.

ListingCardPropertyTypeCopy Anchor Link

ListingCardFeatureCopy Anchor Link

A blank id throws ListingCard features require a non-empty id. A duplicate id throws ListingCard features contain a duplicate id " followed by the trimmed id and a closing quote. The card then renders at most the first four entries. An entry with a blank label and no value is skipped, and later entries do not fill that gap.

ListingCardCtaCopy Anchor Link

LoadingCopy Anchor Link

state must be "loading". This variant accepts only className and labels. It does not accept listing content, href, or cta. The article has aria-busy="true". A non-blank labels.loading is its accessible name. The skeleton is decorative, pulses, and disables that animation under prefers-reduced-motion. It contains no heading, image, price, feature list, or link.

CustomizationCopy Anchor Link

Color comes from four custom properties. Each has a system-color fallback. Set them on an ancestor. The card does not ship theme values.

--ring colors the keyboard focus outline of the single link.

The article is an @container. Below a 40rem container width the image and text stack. From 40rem they sit in a row, and the image area uses 44% of that row. These are container queries, not viewport breakpoints.

className is appended to the article and does not merge conflicting Tailwind utilities.