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

# Theming

> Customize Boxpressd Sites SDK components to match your website's brand.

The Boxpressd Sites SDK is designed to inherit your website's look and feel while still providing polished, consistent components out of the box.

You can customize SDK components globally using the `theme` prop on `BoxpressdProvider` or directly through CSS variables.

## Provider Theme

The simplest way to customize SDK components is through the `BoxpressdProvider`.

```tsx id="eh9mp4" theme={null}
import { BoxpressdProvider } from "@boxpressd/sites-sdk"

export default function App() {
  return (
    <BoxpressdProvider
      apiKey={process.env.NEXT_PUBLIC_BOXPRESSD_API_KEY!}
      theme={{
        primaryColor: "#b8894f",
        secondaryColor: "#2a2a2a",
        borderRadius: "16px"
      }}
    >
      {children}
    </BoxpressdProvider>
  )
}
```

Theme values are merged with the SDK defaults.

## CSS Variables

All Boxpressd components use CSS variables prefixed with:

```css id="1twv5s" theme={null}
--bxp-*
```

This allows you to override component styling from your own stylesheets.

```css id="637g7u" theme={null}
:root {
  --bxp-primary: #b8894f;
  --bxp-secondary: #2a2a2a;
  --bxp-background: #ffffff;
  --bxp-foreground: #1f1f1f;
  --bxp-muted: #f5f1eb;
  --bxp-border: #ddd3c4;
  --bxp-border-radius: 16px;
}
```

## Common Theme Variables

| Variable | Description |
| - | - |
| `--bxp-primary` | Primary brand color used for buttons, highlights, and active states |
| `--bxp-secondary` | Secondary brand color used for supporting accents |
| `--bxp-background` | Default component background |
| `--bxp-foreground` | Default text color |
| `--bxp-muted` | Muted background color |
| `--bxp-muted-foreground` | Muted text color |
| `--bxp-border` | Border color |
| `--bxp-border-radius` | Default border radius |
| `--bxp-card-background` | Card background color |
| `--bxp-card-foreground` | Card text color |

## Example: Lounge Theme

```css id="bb3fx5" theme={null}
:root {
  --bxp-primary: #b8894f;
  --bxp-secondary: #3a2416;
  --bxp-background: #fffaf3;
  --bxp-foreground: #1f1611;
  --bxp-muted: #f3eadf;
  --bxp-muted-foreground: #6f6258;
  --bxp-border: #d8c6ad;
  --bxp-border-radius: 18px;
  --bxp-card-background: #ffffff;
  --bxp-card-foreground: #1f1611;
}
```

## Example: Dark Theme

```css id="qv7p4t" theme={null}
:root {
  --bxp-primary: #d3a966;
  --bxp-secondary: #8b5e3c;
  --bxp-background: #111111;
  --bxp-foreground: #f5f1eb;
  --bxp-muted: #1f1f1f;
  --bxp-muted-foreground: #b8aea3;
  --bxp-border: #33281f;
  --bxp-border-radius: 14px;
  --bxp-card-background: #181818;
  --bxp-card-foreground: #f5f1eb;
}
```

## Scoped Overrides

You can scope theme overrides to a specific area of your website.

```tsx id="fulp6b" theme={null}
<section className="featured-events">
  <BoxpressdEventList />
</section>
```

```css id="38dt4r" theme={null}
.featured-events {
  --bxp-primary: #d3a966;
  --bxp-card-background: #1a1a1a;
  --bxp-card-foreground: #ffffff;
  --bxp-border: rgba(255, 255, 255, 0.12);
}
```

This is useful when one section of the page has a different background or visual treatment than the rest of the site.

## Component-Level Styling

Most SDK components also accept standard React props such as `className`.

```tsx id="44x0t2" theme={null}
<BoxpressdEventList
  className="my-custom-events-section"
  status="upcoming"
/>
```

Then style the wrapper in your application stylesheet:

```css id="a7rghg" theme={null}
.my-custom-events-section {
  margin-top: 4rem;
}
```

Use `className` for layout and spacing.

Use CSS variables for colors, typography, borders, and component appearance.

## Working With Tailwind CSS

If your application uses Tailwind CSS, you can still use Boxpressd CSS variables.

```tsx id="xpkk4v" theme={null}
<section className="rounded-2xl border p-8 [--bxp-primary:#d3a966] [--bxp-border-radius:18px]">
  <BoxpressdEventList status="upcoming" />
</section>
```

For global theming, place variables in your main CSS file.

```css id="npz1sr" theme={null}
@layer base {
  :root {
    --bxp-primary: #d3a966;
    --bxp-border-radius: 18px;
  }
}
```

## Best Practices

### Start With Global Variables

Configure your primary colors and border radius globally first.

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

### Use Scoped Overrides for Special Sections

Use section-level overrides for hero areas, dark sections, or featured content.

```css id="rm3eib" theme={null}
.dark-section {
  --bxp-background: #111111;
  --bxp-foreground: #ffffff;
  --bxp-card-background: #181818;
}
```

### Avoid Styling Internal Elements Directly

Prefer CSS variables and documented props over targeting internal SDK class names.

Internal markup may change between releases.

## Troubleshooting

### Theme Changes Are Not Appearing

Check that:

* Your CSS is loaded after SDK styles.
* The provider wraps the component tree.
* CSS variables are defined on a parent element of the SDK component.
* The variable name is spelled correctly.

### Colors Look Different Than Expected

Remember that SDK components may use hover, muted, border, or foreground variables in addition to the primary color.

Update the supporting variables for a more complete theme.

### Dark Sections Have Low Contrast

Set both background and foreground variables when placing components on dark backgrounds.

```css id="gbzqk6" theme={null}
.dark-section {
  --bxp-background: #111111;
  --bxp-foreground: #ffffff;
  --bxp-muted-foreground: #c7bfb6;
}
```

## Next Steps

Now that your theme is configured, continue to:

* Components Overview
* Events
* Reviews
* Maps

These guides explain how to add styled Boxpressd components throughout your website.