Blog grid
A blog index with a featured post, category filter, post cards, pagination and an in-place reader.
pnpm dlx shadcn@latest add @uiarc/blog-gridLive block · sample data
- A marketing site blog or journal index.
- Resource hubs with a few categories and a featured story.
- Use changelog-page for release notes with versions.
- Use a data table for large archives that need sorting and search.
Installation
Add Blog grid with the shadcn CLI, or copy the source by hand.
pnpm dlx shadcn@latest add @uiarc/blog-gridAdds the block and its local dependencies, and installs motion, lucide-react. First time? Add the @uiarc registry to components.json, or use the full URL:
Usage
Use this as the index of a blog, journal or news page. Load posts from your CMS into blog-grid-data.ts or the posts prop, pass getHref to link each card to its article route, and keep category and page in your URL through the controlled props.
example.tsx
import { BlogGrid } from "@/registry/blocks/blog-grid/blog-grid"; export function BlogIndex({ posts }: { posts: BlogPost[] }) { return ( <BlogGrid posts={posts} categories={["Product", "Design", "Engineering", "Company"]} getHref={post => `/blog/${post.id}`} /> );}API reference
2 parts. The first is the root.
BlogGrid
A blog index: title, category filter with a gliding highlight, a large featured post, a responsive card grid and pagination. Without getHref, cards open an in-place reader whose image morphs out of the card.
PropTypeDefaultDescription
postsBlogPost[]sample postsPosts to list. Sorted newest first by date.categoriesstring[]–Filter labels in order. "All" is added in front.titlestring"Journal"Section heading.descriptionstring–Line under the heading. Pass an empty string to hide it.categorystring–Active category, or "All" (controlled).defaultCategorystring"All"Initial category when uncontrolled.onCategoryChange(category: string) => void–Called when a filter is picked. The page resets to 1.pagenumber–One based page (controlled).defaultPagenumber1Initial page when uncontrolled.onPageChange(page: number) => void–Called from the page numbers and the previous and next buttons.pageSizenumber6Cards per page below the featured post.showFeaturedbooleantrueShows the post marked featured (or the newest) of the current filter as a large card on page one.getHref(post: BlogPost) => string–Link for each post. When set, cards are plain links and the in-place reader is off.onPostOpen(post: BlogPost) => void–Called when a post opens, for analytics or routing.classNamestring–Extra class on the section.BlogPost
One post.
PropTypeDefaultDescription
idRequiredstring–Stable id, also the fallback hash link.titleRequiredstring–Card and reader title.excerptRequiredstring–Two line summary on cards, the lead paragraph in the reader.categoryRequiredstring–Must match one of categories to be filterable.dateRequiredstring–ISO date (YYYY-MM-DD).readTimeRequirednumber–Minutes to read.authorRequired{ name: string; avatar?: string; role?: string }–Byline.image{ src: string; alt: string }–Cover image. Cards crop it to 3:2.bodystring[]–Paragraphs for the in-place reader.featuredboolean–Prefer this post for the featured slot.- Tab
- Moves through filters, cards, and pagination.
- Enter
- Opens the focused post, or picks the focused filter or page.
- Space
- Picks the focused filter or page.
- Filters are buttons with aria-pressed; pagination is a nav with aria-current on the active page.
- Each card is one link with the title, excerpt and byline as its content, so screen readers announce it once.
- The reader moves focus to its back button, and closing returns focus to the card you opened.
- Images carry real alt text; author avatars are decorative.
- The filter and page highlights glide on the morph spring.
- Filtering crossfades the grid with a short rise; paging slides it in the direction of travel.
- Opening a post morphs the card image into the reader hero, and back on close.
- Card images zoom 3% on hover (fine pointers only).
- Reduced motion swaps travel and morphs for plain fades.
- Three columns above 900px, two to 540px, then one.
- The featured post stacks its image above the text below 680px.
- Filters scroll sideways on phones; Previous and Next collapse to arrows.
- Only one page of cards renders at a time; images below the fold load lazily.
- Transitions animate transform and opacity only.
Notes for AI
Give your coding assistant the Markdown reference instead of screenshots.
- Choose this for a blog, journal, news or resources index.
- Pass getHref for real article routes; leave it out for a self-contained demo or a small site that reads posts in place.
- Drive category and page from the URL with the controlled props so the index is linkable.
The full library index for assistants is at /llms.txt.
