Skip to main content
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. 
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: 
--bxp-*
This allows you to override component styling from your own stylesheets. 
: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

VariableDescription
--bxp-primaryPrimary brand color used for buttons, highlights, and active states
--bxp-secondarySecondary brand color used for supporting accents
--bxp-backgroundDefault component background
--bxp-foregroundDefault text color
--bxp-mutedMuted background color
--bxp-muted-foregroundMuted text color
--bxp-borderBorder color
--bxp-border-radiusDefault border radius
--bxp-card-backgroundCard background color
--bxp-card-foregroundCard text color

​
Example: Lounge Theme

: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

: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. 
<section className="featured-events">
  <BoxpressdEventList />
</section>

.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. 
<BoxpressdEventList
  className="my-custom-events-section"
  status="upcoming"
/>
Then style the wrapper in your application stylesheet: 
.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. 
<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. 
@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. 
: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. 
.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. 
.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.