List

Section component for displaying a grid of cards (DefaultCard or IconCard).

Props

Prop	Type	Required	Default	Description
`title`	`string`	No	-	Section title
`title_tag`	`'h1' \| 'h2' \| 'h3' \| 'h4' \| 'p'`	No	`'h3'`	HTML tag for title
`title_variant`	`TypographyVariant`	No	`'section-heading'`	Typography variant for title styling
`description`	`JSONRTE`	No	-	Rich text description
`view_all_link`	`Link`	No	-	"View all" link
`cards`	`Card[]`	No	`[]`	Array of card objects
`linked_cards`	`LinkedCard[]`	No	`[]`	Array of linked card objects
`columns`	`number`	No	`2`	Number of grid columns
`card_type`	`'default' \| 'icon'`	No	`'default'`	Type of card to render
`icon_variant`	`'default' \| 'centered'`	No	`'default'`	Icon card variant
`icon_size`	`'default' \| 'small'`	No	`'default'`	Icon card size
`align`	`'full' \| 'left'`	No	`'full'`	Grid alignment
`$`	`CSLPFieldMapping`	No	-	CSLP mapping for editable fields
`noPadding`	`boolean`	No	`false`	Removes section padding (used when nested in TwoColumn)
`priorityFirstImage`	`boolean`	No	`false`	Loads the first card's image eagerly with high fetch priority (injected by ComponentsRenderer for above-the-fold lists)

Usage

1import { List } from '@/components/organisms/List';
2
3<List
4  title="Featured Articles"
5  title_tag="h2"
6  description={richTextContent}
7  cards={cardData}
8  columns={3}
9  card_type="default"
10  view_all_link={{ href: "/blog", title: "View All Articles" }}
11/>

import { List } from '@/components/organisms/List';

<List
  title="Featured Articles"
  title_tag="h2"
  description={richTextContent}
  cards={cardData}
  columns={3}
  card_type="default"
  view_all_link={{ href: "/blog", title: "View All Articles" }}
/>

Features

Flexible cards: Supports both cards and linked_cards
Card types: DefaultCard or IconCard
Responsive grid: Adapts columns based on breakpoints
View all link: Optional "View all" link in header
Rich description: Supports rich text description
Typography variants: Supports custom title styling via title_variant prop
Alignment: Full width or left-aligned
Above-the-fold priority: When placed at index 0 or 1 in a page, ComponentsRenderer automatically injects priorityFirstImage, causing the first card's image to load with fetchPriority="high" and loading="eager"

Title Variants

The title_variant prop allows you to customize the typography styling of the section title. Defaults to 'section-heading' if not provided. Accepts any value from the Title component's TypographyVariant type:

"cs-h1-display", "h1-standard", "h1-compact", "h1-display-compact"
"cs-h1-header", "cs-h1-3xl"
"cs-h2", "cs-h3", "cs-h4", "cs-h5", "cs-h6"
"hero-text", "section-heading"

Grid Columns

Responsive breakpoints:

Mobile: 1 column
Tablet: 2-4 columns (based on columns prop)
Desktop: 2-8 columns (based on columns prop)

Card Mapping

Maps cards and linked_cards to unified CardData format
Supports custom_card_query results (merged into linked_cards)

Static Card Image Fallback

For static cards (from the cards prop), when no image is uploaded in the CMS, the image_url field is used as a fallback. This allows authors to provide an external image URL (e.g., from a CDN or third-party source) when they cannot upload directly to Contentstack.

Priority: Uploaded image is used first; if absent, image_url is used
Works in both card types: DefaultCard and IconCard both receive the resolved image and render via MediaItem
Live Preview: When the fallback is used, the image_url field remains editable in Live Preview

Automatic OG Image Fallback

For both static cards and linked entry cards, if no card image is available (image and image_url are both missing), the card now uses the automatic OG image endpoint (/api/og) as a final fallback.

Order: Uploaded image -> image_url -> generated OG image
Scope: Applies to both DefaultCard and IconCard rendering paths
Source: The fallback image is generated from card title, content type, and URL path

Custom Card Query

The custom_card_query prop allows you to dynamically fetch cards based on query parameters. Results are automatically merged into linked_cards at the data fetching level.

Custom Card Query Properties

Property	Type	Required	Description
`content_type`	`'page' \| 'blogpost' \| 'guide' \| 'person' \| 'live_stream' \| 'kickstart'`	Yes	Content type to query
`terms`	`string[]`	No	Array of taxonomy term UIDs to filter by
`limit`	`number`	No	Maximum number of results (default: 10)
`order_by`	`'date' \| 'alphabetical'`	No	Sort field (default: 'date')
`sort`	`'DESC' \| 'ASC'`	No	Sort order (default: 'DESC')

Example

1<List
2  title="Related Guides"
3  custom_card_query={{
4    content_type: 'guide',
5    terms: ['ai', 'headless'],
6    limit: 6,
7    order_by: 'date',
8    sort: 'DESC'
9  }}
10/>

<List
  title="Related Guides"
  custom_card_query={{
    content_type: 'guide',
    terms: ['ai', 'headless'],
    limit: 6,
    order_by: 'date',
    sort: 'DESC'
  }}
/>

Notes

Uses mapCardsToCardData and mapLinkedCardsToCardData utilities (see lib/transform/listUtils.ts)
Icon cards use IconCard component with variant/size props
Default cards use DefaultCard component
Grid uses CSS Grid with responsive column classes
Custom card query results are filtered client-side for taxonomy terms
Guide chapters (entries with chapter: true) are automatically filtered out