Blog index

Code

<BlogIndex  title="Blog"  description="Notes on design and engineering."  posts={posts}  postHref={(p) => `/blog/${p.slug}`}/>

Website · beta

Live examples and controls: Blog index in the lab.

InstallCopy Anchor Link

npx shadcn@latest add https://docs.nasaqui.com/r/blog-index.json

The landing page of a blog. A featured post on top, a search box, category and tag chips, a grid of post cards (cover, category, title, excerpt, date and reading time) and pagination. It is controlled or uncontrolled for both filters and the page, so you can keep them in the URL.

When to useCopy Anchor Link

• The list page of a blog, a changelog of articles or a news section.
• A "latest writing" row: use PostCard on its own, or ProfileWriting.

When not to useCopy Anchor Link

• A table of records with sortable columns: use Table.
• One article: use BlogPost.

ImportCopy Anchor Link

import { BlogIndex, PostCard } from "@fadymondy/nasaq/web";

Quick startCopy Anchor Link

<BlogIndex
  title="Blog"
  description="Notes on design and engineering."
  posts={posts}
  postHref={(p) => `/blog/${p.slug}`}
/>

AnatomyCopy Anchor Link

BlogIndex                 data-slot="blog-index"
├─ SectionHeader          title, description, actions
├─ featured PostCard      variant="featured" (newest post marked featured, else newest)
├─ toolbar                search InputGroup with clear button, category ChipGroup, tag ChipGroup
├─ post grid              PostCard x pageSize, container-query columns
├─ EmptyState             when nothing matches
└─ Pagination

APICopy Anchor Link

BlogIndexCopy Anchor Link

PostCard and PostCoverCopy Anchor Link

PostCard takes post, href, onOpen, variant (default, featured, compact) and labels. The title is a stretched link, so the whole card is one target with one tab stop. PostCover shows post.cover or, without one, art generated from the slug using the --nq-tag-* tokens.

Model helpersCopy Anchor Link

Pure functions, importable in Node: filterPosts, sortByDate, paginate, pickFeatured, postCategoryCounts, tagCounts, relatedPosts, adjacentPosts, readingTime, extractToc, slugifyHeading, activeHeadingId, readingProgress, remarkCallouts.

AccessibilityCopy Anchor Link

• The search is a labelled field; the result count is announced in a polite live region.
• Filter chips are toggle buttons with aria-pressed.
• Each card is an <article> with one link; the cover is decorative.
• Pagination is a nav with aria-current="page".

RTL & i18nCopy Anchor Link

Strings come from the provider locale (English, Arabic) and can be overridden with labels. Dates and numbers use Latin digits. Layout uses logical classes only.

StylingCopy Anchor Link

Container queries choose the columns (1, 2 or 3), so the block adapts to its parent and not the window. Covers use tokens, no hex.

Do / Don'tCopy Anchor Link

• Do give every post a readingMinutes, or compute it from the body with readingTime.
• Do keep filters in the URL for shareable views.
• Don't pass a partial list and expect server paging: BlogIndex pages what it is given.

RelatedCopy Anchor Link

BlogPost, Pagination, SectionHeader.

LabCopy Anchor Link

Story Components/Layout/Blog Index and page story Pages/Public/Blog.