Skip to Content

Event Section

Present upcoming and past events with date-aware filtering, venue details, categories, and links.

EventSection renders event data supplied by the application. It does not create events, manage registrations, or reserve tickets.

Basic usage

Use ISO date strings for startDate and optional endDate. Provide friendly display labels when the application's timezone or preferred date format should be explicit.

390 × 844

Variants and filtering

The upcoming and past variants initialize the date filter accordingly. Other variants start with all events. The user can switch between all, upcoming, and past, and filter by category.

grid - Browse upcoming programs in a card grid.

390 × 844

list - Scan dates, categories, and venues quickly.

390 × 844

featured - Promote a highlighted event.

390 × 844

calendar - Group dates into a calendar-oriented list.

390 × 844

timeline - Present events as a chronological timeline.

390 × 844

upcoming - Focus on events that have not ended.

390 × 844

past - Review previously held events.

390 × 844

cards - Give events distinct card surfaces.

390 × 844

split - Separate featured and supporting events.

390 × 844

carousel - Scroll through events with the UI carousel.

390 × 844
VariantUse case
gridBrowse an event collection.
listScan a compact chronological list.
featuredPromote one event above the rest.
calendarPresent a date-oriented list.
timelineShow events along a chronological sequence.
upcomingStart with events that have not ended.
pastStart with completed events.
cardsGive each event its own card surface.
splitSeparate featured and supporting events.
carouselBrowse events with the UI Carousel controls.
390 × 844

Date behavior

  • An event is past when its endDate (or startDate when no end is supplied) is strictly earlier than referenceDate.
  • An event ending exactly at the reference instant is still considered upcoming.
  • Invalid dates and end dates earlier than start dates throw a RangeError; fix the source data rather than silently showing a misleading status.
  • Pass referenceDate during SSR when a stable server/client classification is important.

Accessibility and API

  • Event titles use headings and optional native links; dates use semantic <time> elements.
  • Filter controls are keyboard-operable, and date selections expose aria-pressed.
  • Category labels and prices are caller data; use currency values appropriate to the event's locale.
  • Responsive layouts collapse to one column on mobile; carousels reuse the UI Carousel.
PropTypeRequiredDefaultDescription
eventsreadonly EventItem[]Yes—Caller-provided events; IDs must be unique.
variantEventSectionVariantNogridLayout variant.
featuredEventIdstringNoFirst featured itemExplicit featured event.
filterablebooleanNotrueShow date and category filters.
referenceDatestring | DateNoCurrent timeDate boundary for past/upcoming classification.
emptyStateReactNodeNo—Additional no-results content.

EventItem supports id, title, startDate, endDate, dateLabel, endLabel, description, location, category, price, href, image, and featured.

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 { EventSection } from "@puzzle-ui/pieces";

type EventSectionProps = ComponentProps<typeof EventSection>;

export function CustomizedSection(props: EventSectionProps) {
  return (
    <EventSection
      {...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 { EventSection } from "@puzzle-ui/pieces";

type EventSectionProps = ComponentProps<typeof EventSection>;

export function SectionWrapper(props: EventSectionProps) {
  return <EventSection {...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.