Skip to Content

Activity Section

Display searchable, grouped, and linked activity records in product and admin interfaces.

ActivitySection presents records supplied by the application. It does not fetch events, apply permissions, or decide which activity is visible.

390 × 844

Variants

Use the variant gallery to compare timeline, list, cards, and audit-oriented presentations with the same realistic events.

timeline - Connect changes along a vertical thread.

390 × 844

list - Keep events compact and scannable.

390 × 844

feed - Show a conversational activity stream.

390 × 844

grouped - Separate records under date or topic headings.

390 × 844

cards - Give each record a distinct card.

390 × 844

compact - Fit recent updates into a dense dashboard.

390 × 844

avatars - Give actor identities more visual weight.

390 × 844

audit - Present a sequence of administrative changes.

390 × 844

split - Lay events out in two responsive columns.

390 × 844

horizontal - Scroll through a short event rail.

390 × 844

Filtering

Filter the source data in your application and pass the result as items. The example filters by category and keeps the selected filter in caller-owned state.

390 × 844

Supported variants: timeline, list, feed, grouped, cards, compact, avatars, audit, split, and horizontal.

Accessibility

  • Each section is labelled by its heading. Events use ordered lists, semantic <time> elements, and native links when href is provided.
  • Supply stable unique item IDs. group controls grouping and groupLabel supplies the displayed heading.
  • category and metadata are application-defined fields for filtering and supplementary information.
  • Empty data uses the shared EmptyStatePanel composition. Supply a custom emptyState message when the default is not appropriate.
  • Use renderItem only when the default actor/action/time/metadata presentation does not meet the product's needs.

API

PropTypeRequiredDefaultDescription
itemsreadonly ActivityItem[]Yes—Activity records; IDs must be unique.
titleReactNodeNo"Recent activity"Section heading.
emptyStateReactNodeNoInformational messageAdditional empty-state content.
actionsReactNodeNo—Caller-provided section actions.
variantActivitySectionVariantNofeedActivity layout.
renderItem(item: ActivityItem) => ReactNodeNoDefault record layoutCustom event renderer.
classNamestringNo—Additional root class.

ActivityItem supports id, actor, action, timestamp, dateTime, icon, description, metadata, group, groupLabel, category, and href.

Customization

Use the component's className and documented slots to adapt the composition. Prefer a caller-provided ReactNode for media, actions, or controls rather than adding domain behavior to the section.

import type { ComponentProps } from "react";
import { ActivitySection } from "@puzzle-ui/pieces";

type ActivitySectionProps = ComponentProps<typeof ActivitySection>;

export function CustomizedSection(props: ActivitySectionProps) {
  return (
    <ActivitySection
      {...props}
      className={[props.className, "brand-section"].filter(Boolean).join(" ")}
    />
  );
}

Responsive behavior

Use the preview device selector to review mobile, tablet, and desktop widths. The built-in variant controls section structure; ensure application-provided media, form controls, and children can shrink or wrap without horizontal overflow. Use the existing responsive breakpoints in scoped CSS when the consuming layout needs a product-specific adjustment.

Theme support

The section consumes semantic variables from @puzzle-ui/theme and inherits active or scoped themes. Wrap the application with Theme, and use semantic roles such as text, surface, border, and primary for local overrides. Avoid hard-coded colors, spacing, radii, and shadows.

.brand-section {
  color: var(--puzzle-color-text);
  background: var(--puzzle-color-surface);
  border-color: var(--puzzle-color-border);
}

Composition

Compose this section with the UI primitives named in its API and use the documented slots for consumer-owned controls or media. Keep data fetching, routing, validation, permissions, and persistence in the application. The children slot is intended for additional content that belongs with this section, not as a substitute for its typed data model.

TypeScript example

The package exports this component from its root. Derive a wrapper's exact prop type from the public component rather than widening it:

import type { ComponentProps } from "react";
import { ActivitySection } from "@puzzle-ui/pieces";

type ActivitySectionProps = ComponentProps<typeof ActivitySection>;

export function SectionWrapper(props: ActivitySectionProps) {
  return <ActivitySection {...props} />;
}

Framework compatibility

The section is router-independent. Static compositions can be server-rendered; place callback-driven interactions in the framework's client boundary. See Next.js and TanStack Start integration for runnable framework examples and SSR guidance.