ArchiveSearchFilter

ArchiveSearchFilter is the filter bar of an archive page: a search field plus one filter per taxonomy (categories, tags and post types), as dropdowns or chips. It holds the selection and reports every change through onFiltersChange; your code filters or re-fetches the listing. Type in the search field or pick a category below.

import { useState } from 'react'
import {
  ArchiveSearchFilter,
  EMPTY_ARCHIVE_FILTERS,
  PostsList,
  type ArchiveFilters,
  type PostView,
} from '@systhemaui/next'

const categories = [
  { id: 'design', label: 'Design' },
  { id: 'engineering', label: 'Engineering' },
  { id: 'editorial', label: 'Editorial' },
]

function post(id: number, title: string, category: string, image: string): PostView {
  const label = categories.find((c) => c.id === category)?.label ?? category
  return {
    id,
    title,
    label,
    category: { name: label, slug: category },
    href: '#',
    tags: [],
    postType: 'article',
    author: { name: 'Mira Kovač' },
    publishedAt: `2026-09-${10 + id}T09:00:00.000Z`,
    media: { url: `/demo-assets/${image}`, alt: '', width: 1800, height: 1200 },
    doc: null,
  }
}

const posts = [
  post(4, 'Designing with tokens from day one', 'design', 'mountains.webp'),
  post(3, 'A calmer content model for editors', 'editorial', 'workspace.webp'),
  post(2, 'Shipping a multilingual site in a week', 'engineering', 'city.webp'),
  post(1, 'A field guide to spacing', 'design', 'coast.webp'),
]

export default function Demo() {
  const [filters, setFilters] = useState<ArchiveFilters>(EMPTY_ARCHIVE_FILTERS)
  const visible = posts.filter(
    (p) =>
      (!filters.categoryId || p.category?.slug === filters.categoryId) &&
      p.title.toLowerCase().includes(filters.q.toLowerCase()),
  )

  return (
    <div className="flex w-full flex-col gap-8">
      <ArchiveSearchFilter
        categories={categories}
        onFiltersChange={setFilters}
        syncUrl={false}
      />
      <PostsList items={visible} view="grid4" />
    </div>
  )
}

ImportLink to this section

import { ArchiveSearchFilter, EMPTY_ARCHIVE_FILTERS } from '@systhemaui/next'

In a React app without Next.js, import them from @systhemaui/react.

How it worksLink to this section

• Each taxonomy with options (categories, tags, types) becomes one filter; a taxonomy with no options is left out. Options are { id, slug?, label }, and the selection stores the id, so you can query by relationship id.
• onFiltersChange receives { q, categoryId, tagId, postType } (EMPTY_ARCHIVE_FILTERS is the empty value). It fires on every change, but not on mount, so the server-rendered first page is not fetched twice.
• Typing updates q after 300 ms; submitting the search form applies it at once.
• Each active filter appears as a removable chip below the bar.
• syncUrl (default true) mirrors the selection into the query string with history.replaceState (?q=…&category=<slug>&tag=<slug>&type=…), so the URL can be shared. It is a mirror only: it never triggers navigation or a server render. Pass initial to seed the filters from that query on the next visit.

Filter stylesLink to this section

filterStyle="dropdown" (default) renders one <select> per taxonomy. filterStyle="chips" renders each taxonomy as a row of toggle Chips; clicking the active chip clears it. Both drive the same state. filtersLabel adds a leading label.

import { ArchiveSearchFilter } from '@systhemaui/next'

export default function Demo() {
  return (
    <div className="w-full">
      <ArchiveSearchFilter
        filtersLabel="Filters"
        filterStyle="chips"
        categories={[
          { id: 1, slug: 'design', label: 'Design' },
          { id: 2, slug: 'engineering', label: 'Engineering' },
          { id: 3, slug: 'editorial', label: 'Editorial' },
        ]}
        syncUrl={false}
      />
    </div>
  )
}

ExamplesLink to this section

Order and labelsLink to this section

order reorders the taxonomies ('categories', 'tags', 'types'; default in that order). Taxonomies you leave out of a partial order follow in their default order. searchable={false} hides the search field, and labels translates the placeholders and the remove-chip names.

import { ArchiveSearchFilter } from '@systhemaui/next'

export default function Demo() {
  return (
    <div className="w-full">
      <ArchiveSearchFilter
        searchable={false}
        order={['tags', 'categories']}
        categories={[
          { id: 1, slug: 'design', label: 'Design' },
          { id: 2, slug: 'engineering', label: 'Engineering' },
        ]}
        tags={[
          { id: 10, slug: 'tokens', label: 'Tokens' },
          { id: 11, slug: 'payload', label: 'Payload' },
        ]}
        types={[
          { id: 'article', label: 'Article' },
          { id: 'video', label: 'Video' },
        ]}
        labels={{ allCategories: 'All categories', allTags: 'All tags', allTypes: 'All types' }}
        syncUrl={false}
      />
    </div>
  )
}

Re-fetching from an APILink to this section

For a long archive, re-fetch the first page when the filters change and hand it to PostsList, which resets its paging when items changes. A Payload project has this wired up already: ArchiveFilterProvider, ArchiveFilterControl and PostsListClient from @systhemaui/payload/next, described in Archive pages.

'use client'

import { useEffect, useState } from 'react'
import {
  ArchiveSearchFilter,
  EMPTY_ARCHIVE_FILTERS,
  PostsList,
  type ArchiveFilterOption,
  type PostView,
} from '@systhemaui/next'

export function Archive({
  firstPage,
  categories,
}: {
  firstPage: PostView[]
  categories: ArchiveFilterOption[]
}) {
  const [filters, setFilters] = useState(EMPTY_ARCHIVE_FILTERS)
  const [items, setItems] = useState(firstPage)

  useEffect(() => {
    if (filters === EMPTY_ARCHIVE_FILTERS) return
    const query = new URLSearchParams({ q: filters.q, category: String(filters.categoryId ?? '') })
    fetch(`/api/journal?${query}`)
      .then((response) => response.json())
      .then(setItems)
  }, [filters])

  return (
    <>
      <ArchiveSearchFilter categories={categories} onFiltersChange={setFilters} />
      <PostsList items={items} view="grid3" />
    </>
  )
}

PropsLink to this section

HTML and CSSLink to this section

The search field is a SearchField and the dropdowns use the FormSelect markup, so they share the form input tokens. The .archive-filter* hooks of the posts CSS layer lay them out: the fields share one wrapping row (each at least 16rem), and the active chips use the chip tokens.

<div class="archive-filter archive-filter-dropdown">
  <div class="archive-filter-bar">
    <form class="archive-filter-search" role="search">
      <!-- SearchField markup, aria-label="Search…" -->
    </form>
    <div class="form-select-wrapper archive-filter-select archive-filter-select-category">
      <select class="form-select" aria-label="Select a category">
        <option value="">Select a category</option>
        <option value="1">Design</option>
      </select>
      <span class="form-select-icon" aria-hidden="true"></span>
    </div>
  </div>
  <div class="archive-filter-active">
    <button type="button" class="archive-filter-chip" aria-label="Remove filter Design">
      <span class="archive-filter-chip-label">Design</span>
      <span class="archive-filter-chip-remove" aria-hidden="true">×</span>
    </button>
  </div>
</div>

Next.jsLink to this section

@systhemaui/next re-exports ArchiveSearchFilter from @systhemaui/react unchanged. It is a client component. In a Payload project, use the archive filter pipeline from @systhemaui/payload/next; see Archive pages.

AccessibilityLink to this section

• The search field sits in a role="search" form and is named by its placeholder.
• Each dropdown is named by its placeholder ("Select a category"); each chip group is a role="group" with the same name, and the active chip has aria-pressed="true".
• Each removable chip is a button named "Remove filter " (labels.removeFilter translates it).
• Changes do not move focus. Pair the filter with a listing that announces its result, as PostsList does for its empty state.

RelatedLink to this section

• PostsList
• Archive pages
• SearchField