---
title: Public event listings
description: Add saved public Events to an existing site with the Lockerverse SDK.
sidebar:
  order: 8
---

Connect the existing Events section instead of adding a duplicate list. Keep the
host's page structure and light/dark theme. Import only the public Events entry
and its CSS. The SDK owns loading, retry, empty states, paging, image cards, and
sharing. Keep event links as supplied. Do not add ticket checkout or registration
controls unless separately requested. Configure dates and sorting through the
hook; do not fetch and sort Events in separate page code.

## Public event listings

Use the public Events entry to show publicly listed Events that are happening
now, start in the future, or have ended. It does not load ticket or payment UI.

```tsx
import {
  LockerversePublicEvents,
  useLockerversePublicEvents,
} from "@lockerverse/react/public-events";
import "@lockerverse/react/public-events.css";

function CommunityEvents() {
  const events = useLockerversePublicEvents({ communitySlug: "auburn" });
  return <LockerversePublicEvents events={events} title="Events" theme="light" />;
}
```

The hook returns `client`, `events`, `loading`, `error`, and `refresh`. The
component takes the full hook result so it can show loading, empty, and retry
states. `title` sets the visible heading, `showHeading` can hide it, and
`timeZone` controls date display. The default time zone is
`America/New_York`. Use `style` with `LockerverseStyle` tokens or `className`
to match the host site. Links open in a new tab when they use HTTP or HTTPS.
Events can include an optional `imageUrl`. The list uses image cards when an
image is present and a date tile when it is absent. The default view groups
events into "Happening now" and "Upcoming". The "Past Events" view loads on
demand and offers "Load more" for older events. Each card has a share action.
Sharing uses the event link when one exists; otherwise it uses a link to the
event card on the host page. For a one-list view, a card link can load up to
five more pages to find its Event. The visitor can still use Load more.

Pass one configuration object to the hook for a different list. The component
reads that configuration from the hook result. With `showTabs: false`, it shows
one full-width list; `includePast` selects whether that list includes ended
Events. `from`, `to`, and `sort` set the server-side date range and order.
Without `from` or `to`, a one-list view reads all publicly listed Event
history. It includes past Events by default and sorts by descending start
time, so newer Events appear first. With `includePast: false`, the default is
ascending start time for current and future Events. Each page has 20 Events.

```tsx
const config = {
  showTabs: false,
  includePast: true,
  from: "2026-09-01T00:00:00.000Z",
  to: "2026-10-01T00:00:00.000Z",
  sort: "startAtAsc",
} as const;
const events = useLockerversePublicEvents(
  { communitySlug: "auburn" },
  { config, initialPage }
);
return <LockerversePublicEvents events={events} />;
```

For server rendering, obtain `initialPage` with the SDK client's `search()`
and the same date, scope, sort, and page size. Without this configuration,
`initialEvents` from `list()` keeps the original Upcoming and Past views.


Date bounds are ISO instants. An Event is included when its time overlaps the
range: `from` is inclusive and `to` is exclusive. Omit either bound when it is
not needed. `showTabs` and `includePast` are independent. Match an SSR seed to
the same community, date range, sort, and page size. Keep available data visible
when a browser refresh fails. Use the shared integration guide for static-site
limits and verification.

## Public attendee lists

Add an attendee list only when the resource prompt requests it and public
listing is enabled. Use `createLockerversePublicApiClient` and
`getPublicEventAttendees` from `@lockerverse/sdk`; do not build the API endpoint.
The generated client takes the API **origin**, without `/api`. Use `publicApiOrigin` when supplied; otherwise derive it with
`new URL(apiBaseUrl).origin` for the supplied standard Lockerverse API URL.
Pass that client, `path: { communitySlug, eventId }`, and `throwOnError: true`
to each request. Read `data` only after success inside `try`; show a retry action
in `catch`. Pass each `data.nextCursor` as `query.cursor` until it is null.

Display only attendee names from `data.registrations`. Do not display party
size, total counts, email addresses, or other registration values. Match the
existing page and include loading, empty, and error states. The generated
public API types and the installed Core SDK README define the response.