> ## 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.

# Sessions

> Display real-world smoking activity from the Boxpressd community.

Sessions are one of the most unique features available through the Boxpressd ecosystem.

They allow lounges, brands, and retailers to showcase real-world smoking activity happening within their communities. By displaying recent sessions, businesses can demonstrate engagement, highlight popular cigars, and provide visitors with social proof that their products and venues are actively enjoyed.

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

## Available Components

| Component | Description |
| - | - |
| `BoxpressdSessionsFeed` | Displays a collection of recent smoking sessions. |
| `BoxpressdSessionCard` | Displays an individual smoking session. |

## BoxpressdSessionsFeed

The sessions feed automatically loads recent activity associated with the active business.

### Example

```tsx id="2k4h5y" theme={null}
import { BoxpressdSessionsFeed } from "@boxpressd/sites-sdk/sessions"

export default function CommunitySection() {
  return (
    <BoxpressdSessionsFeed
      limit={10}
    />
  )
}
```

### Props

| Prop | Type | Description |
| - | - | - |
| `limit` | `number` | Maximum number of sessions to display. |
| `layout` | `"list" \| "grid"` | Display layout. |
| `showAvatars` | `boolean` | Display user avatars when available. |
| `showRatings` | `boolean` | Display session ratings. |
| `showDuration` | `boolean` | Display smoking duration. |
| `showCigarImage` | `boolean` | Display cigar artwork when available. |
| `className` | `string` | Additional CSS classes. |

## List Layout

```tsx id="o9b2vq" theme={null}
<BoxpressdSessionsFeed
  limit={10}
  layout="list"
/>
```

## Grid Layout

```tsx id="lhkjvh" theme={null}
<BoxpressdSessionsFeed
  limit={6}
  layout="grid"
/>
```

## BoxpressdSessionCard

Display a single session.

This component is useful when building custom layouts or combining sessions with other content.

### Example

```tsx id="a6bpza" theme={null}
import { BoxpressdSessionCard } from "@boxpressd/sites-sdk/sessions"

<BoxpressdSessionCard
  session={session}
/>
```

### Props

| Prop | Type | Description |
| - | - | - |
| `session` | `BoxpressdSession` | Session data object. |
| `showRatings` | `boolean` | Display rating information. |
| `showDuration` | `boolean` | Display smoking duration. |
| `showCigarImage` | `boolean` | Display cigar artwork. |
| `className` | `string` | Additional CSS classes. |

## Session Object

```ts id="5g2v6v" theme={null}
type BoxpressdSession = {
  id: string
  createdAt: string
  startedAt?: string
  endedAt?: string
  durationSeconds?: number
  rating?: number
  note?: string
  user: {
    id?: string
    displayName: string
    avatarUrl?: string
  }
  cigar?: {
    id: string
    name: string
    brandName?: string
    imageUrl?: string
  }
  venue?: {
    id: string
    name: string
  }
}
```

## Username Normalization

The SDK automatically generates a user-friendly display name using the following fallback order:

```ts id="lxtiq9" theme={null}
display_name → first_name + last initial → "Boxpressd User"
```

This helps preserve privacy while maintaining an engaging community experience.

## Example: Recent Activity

```tsx id="6m0ixs" theme={null}
<section>
  <h2>What People Are Smoking</h2>

  <BoxpressdSessionsFeed
    limit={5}
  />
</section>
```

## Example: Brand Community Feed

Brands can use sessions to showcase how customers are enjoying their cigars.

```tsx id="ij12hi" theme={null}
<BoxpressdSessionsFeed
  limit={12}
  layout="grid"
/>
```

This is especially effective for:

* Product launch pages
* Brand homepages
* Featured cigar campaigns
* Community sections

## Example: Lounge Activity Feed

Lounges can use sessions to highlight community engagement.

```tsx id="4q7n2q" theme={null}
<BoxpressdSessionsFeed
  limit={10}
  showRatings
  showDuration
/>
```

## Displaying Ratings

When available, session ratings can help highlight highly-rated cigars.

```tsx id="5bz2ee" theme={null}
<BoxpressdSessionsFeed
  showRatings
/>
```

## Displaying Duration

Session duration can provide additional context about the smoking experience.

```tsx id="xct2vr" theme={null}
<BoxpressdSessionsFeed
  showDuration
/>
```

Typical durations may represent:

* Short smoke breaks
* Lounge visits
* Extended smoking sessions
* Event participation

## Displaying Cigar Artwork

When cigar imagery is available, it can be displayed alongside session information.

```tsx id="ixn81r" theme={null}
<BoxpressdSessionsFeed
  showCigarImage
/>
```

This can significantly increase engagement on community-focused pages.

## Styling

Session components inherit Boxpressd theme variables.

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

## Custom Styling

```tsx id="1ivgq0" theme={null}
<BoxpressdSessionsFeed
  className="community-sessions"
/>
```

```css id="2jk3lf" theme={null}
.community-sessions {
  margin-top: 2rem;
}
```

## Business Awareness

Session components automatically adapt to the active business context.

### Venue

```tsx id="kdbvnh" theme={null}
<BoxpressdSessionsFeed />
```

Displays sessions associated with the active venue.

### Brand

```tsx id="ghyjpu" theme={null}
<BoxpressdSessionsFeed />
```

Displays sessions associated with the active brand.

No manual configuration is required.

## Empty States

Some businesses may have little or no recent session activity.

Components should gracefully handle empty results.

```tsx id="0kv7s8" theme={null}
<BoxpressdSessionsFeed
  emptyMessage="No recent smoking sessions available."
/>
```

## Common Use Cases

### Homepage Community Section

```tsx id="wygk1e" theme={null}
<BoxpressdSessionsFeed
  limit={5}
/>
```

### Brand Community Showcase

```tsx id="ux3f3g" theme={null}
<BoxpressdSessionsFeed
  limit={12}
  layout="grid"
  showCigarImage
/>
```

### Lounge Activity Feed

```tsx id="48vkp5" theme={null}
<BoxpressdSessionsFeed
  limit={10}
  showRatings
  showDuration
/>
```

### Dedicated Community Page

```tsx id="0x7n8h" theme={null}
<BoxpressdSessionsFeed
  limit={25}
  layout="grid"
  showRatings
  showDuration
  showCigarImage
/>
```

## Privacy Considerations

Session components are designed for public-facing websites.

The SDK automatically:

* Uses normalized display names
* Avoids exposing sensitive user information
* Respects visibility settings where applicable

Developers should avoid displaying private user data outside of the information returned by the SDK.

## Best Practices

* Use sessions as social proof.
* Combine sessions with reviews and events.
* Highlight cigar imagery when available.
* Display ratings sparingly to avoid visual clutter.
* Limit homepage feeds to 5–10 items.
* Use larger feeds on dedicated community pages.

## Why Sessions Matter

Unlike traditional website analytics or testimonials, sessions represent real-world engagement from actual cigar enthusiasts.

They provide a unique way to demonstrate:

* Community activity
* Product popularity
* Lounge engagement
* Brand loyalty
* Customer participation

For many businesses, sessions can become one of the most compelling pieces of dynamic content on their website.

## Next Steps

Continue to:

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

These guides cover additional community and engagement features.