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.
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.
list - Scan dates, categories, and venues quickly.
featured - Promote a highlighted event.
calendar - Group dates into a calendar-oriented list.
timeline - Present events as a chronological timeline.
upcoming - Focus on events that have not ended.
past - Review previously held events.
cards - Give events distinct card surfaces.
split - Separate featured and supporting events.
carousel - Scroll through events with the UI carousel.
| Variant | Use case |
|---|---|
grid | Browse an event collection. |
list | Scan a compact chronological list. |
featured | Promote one event above the rest. |
calendar | Present a date-oriented list. |
timeline | Show events along a chronological sequence. |
upcoming | Start with events that have not ended. |
past | Start with completed events. |
cards | Give each event its own card surface. |
split | Separate featured and supporting events. |
carousel | Browse events with the UI Carousel controls. |
Date behavior
- An event is past when its
endDate(orstartDatewhen no end is supplied) is strictly earlier thanreferenceDate. - 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
referenceDateduring 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.
| Prop | Type | Required | Default | Description |
|---|---|---|---|---|
events | readonly EventItem[] | Yes | — | Caller-provided events; IDs must be unique. |
variant | EventSectionVariant | No | grid | Layout variant. |
featuredEventId | string | No | First featured item | Explicit featured event. |
filterable | boolean | No | true | Show date and category filters. |
referenceDate | string | Date | No | Current time | Date boundary for past/upcoming classification. |
emptyState | ReactNode | No | — | Additional no-results content. |
EventItem supports id, title, startDate, endDate, dateLabel, endLabel, description, location, category, price, href, image, and featured.
Related components
- Resource Section for searchable libraries.
- Timeline Section for non-event chronological content.
- Carousel for accessible horizontal navigation.
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.