> ## Documentation Index
> Fetch the complete documentation index at: https://docs.boxpressd.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Events

> Display upcoming, past, and featured Boxpressd events on your website.

The Boxpressd Sites SDK includes a collection of event components designed to help lounges, brands, and other businesses showcase upcoming events, special gatherings, launches, and promotions.

All event components automatically use the business context resolved by the `BoxpressdProvider`.

## Available Components

| Component | Description |
| - | - |
| `BoxpressdEventCard` | Display a single event. |
| `BoxpressdEventListItem` | Compact list view for events. |
| `BoxpressdEventList` | Display multiple events. |
| `BoxpressdEventCalendar` | Calendar-based event view. |
| `EventDetailsModal` | Detailed event modal with actions. |

## BoxpressdEventCard

Display an individual event.

### Example

```tsx id="m4g9wq" theme={null}
import { BoxpressdEventCard } from "@boxpressd/sites-sdk/events"

export default function FeaturedEvent({
  event
}: {
  event: BoxpressdEvent
}) {
  return (
    <BoxpressdEventCard
      event={event}
    />
  )
}
```

### Common Props

| Prop | Type | Description |
| - | - | - |
| `event` | `BoxpressdEvent` | Event data object. |
| `className` | `string` | Additional CSS classes. |
| `showImage` | `boolean` | Display event image. |
| `showDescription` | `boolean` | Display event description. |

## BoxpressdEventListItem

A compact event layout suitable for sidebars, activity sections, and mobile layouts.

### Example

```tsx id="6iqyzw" theme={null}
import { BoxpressdEventListItem } from "@boxpressd/sites-sdk/events"

<BoxpressdEventListItem
  event={event}
/>
```

## BoxpressdEventList

Displays a collection of events.

The component automatically fetches data using the active business context.

### Example

```tsx id="jxd36q" theme={null}
import { BoxpressdEventList } from "@boxpressd/sites-sdk/events"

export default function UpcomingEvents() {
  return (
    <BoxpressdEventList
      status="upcoming"
      limit={6}
    />
  )
}
```

### Props

| Prop | Type | Description |
| - | - | - |
| `status` | `"upcoming" \| "past" \| "all"` | Event filter. |
| `limit` | `number` | Maximum number of events to display. |
| `layout` | `"grid" \| "list"` | Display layout. |
| `featuredOnly` | `boolean` | Show featured events only. |
| `className` | `string` | Additional CSS classes. |

### Grid Layout

```tsx id="jodrjg" theme={null}
<BoxpressdEventList
  status="upcoming"
  layout="grid"
  limit={6}
/>
```

### List Layout

```tsx id="9u1v4l" theme={null}
<BoxpressdEventList
  status="upcoming"
  layout="list"
  limit={10}
/>
```

## BoxpressdEventCalendar

Displays events within a calendar interface.

This component is ideal for event-heavy businesses that host frequent gatherings.

### Example

```tsx id="48x5nt" theme={null}
import { BoxpressdEventCalendar } from "@boxpressd/sites-sdk/events"

export default function CalendarPage() {
  return (
    <BoxpressdEventCalendar />
  )
}
```

### Props

| Prop | Type | Description |
| - | - | - |
| `initialMonth` | `Date` | Initial month displayed. |
| `showPastEvents` | `boolean` | Display past events. |
| `className` | `string` | Additional CSS classes. |

## EventDetailsModal

Displays detailed event information and attendee actions.

### Features

* Event details
* Event image
* Date and time information
* Location details
* Directions links
* Add-to-calendar actions
* Ticket links

### Example

```tsx id="jz9hf7" theme={null}
<EventDetailsModal
  event={event}
  open={open}
  onOpenChange={setOpen}
/>
```

## Add to Calendar

Event components support calendar integrations.

### Google Calendar

```txt id="a34s8u" theme={null}
https://calendar.google.com/calendar/render
```

### ICS Downloads

Generated ICS files allow visitors to add events to:

* Apple Calendar
* Outlook
* Google Calendar
* Yahoo Calendar
* Other calendar applications

## Event Object

```ts id="5pld7l" theme={null}
type BoxpressdEvent = {
  id: string
  title: string
  description?: string
  startsAt: string
  endsAt?: string
  timezone?: string
  locationName?: string
  address?: string
  imageUrl?: string
  featured?: boolean
  externalUrl?: string
  ticketUrl?: string
}
```

## Featured Events

Highlight important events using the `featuredOnly` prop.

```tsx id="2k0cyx" theme={null}
<BoxpressdEventList
  status="upcoming"
  featuredOnly
  limit={3}
/>
```

This is commonly used for:

* Grand openings
* Brand launches
* Cigar release events
* Special promotions
* VIP gatherings

## Server-Side Rendering

Event components work well with server-side rendering.

For advanced use cases, fetch events directly:

```tsx id="7b5hgh" theme={null}
import { getBoxpressdEvents } from "@boxpressd/sites-sdk/events"

const events = await getBoxpressdEvents({
  status: "upcoming",
  limit: 6
})
```

See the Data Fetching documentation for additional details.

## Styling

All event components inherit Boxpressd theme variables.

```css id="7kh4q6" theme={null}
:root {
  --bxp-primary: #d3a966;
  --bxp-border-radius: 16px;
}
```

You can also provide additional styling through standard React props.

```tsx id="0z7ndf" theme={null}
<BoxpressdEventList
  className="my-events-section"
/>
```

## Common Use Cases

### Homepage Events Section

```tsx id="n0lvkh" theme={null}
<BoxpressdEventList
  status="upcoming"
  limit={3}
/>
```

### Dedicated Events Page

```tsx id="psf93h" theme={null}
<BoxpressdEventCalendar />
```

### Featured Event Banner

```tsx id="e0t65j" theme={null}
<BoxpressdEventList
  featuredOnly
  limit={1}
/>
```

### Sidebar Widget

```tsx id="fkh07g" theme={null}
<BoxpressdEventList
  layout="list"
  limit={5}
/>
```

## Best Practices

* Display upcoming events on your homepage.
* Use featured events for major promotions.
* Provide add-to-calendar actions whenever possible.
* Include event images for better engagement.
* Limit homepage event sections to 3–6 items.
* Use the calendar view for event-heavy businesses.

## Next Steps

Continue to:

* Reviews
* Maps
* Check-ins
* Sessions
* Data Fetching → Events

These guides cover additional components and advanced event integrations.