Styling
Configure Tailwind CSS theme variables for the Shelby Media Player
Overview
The Shelby Media Player uses custom Tailwind CSS color utilities prefixed with sp- (Shelby Player). These colors are used for player controls that appear over video content and must be defined in your application's CSS.
Without defining these colors, player controls like the seekbar, buttons, and menus will be invisible or incorrectly styled.
TailwindCSS 4 Setup
Import Player Styles (Recommended)
The simplest setup is to import one of the playerâs prebuilt stylesheets (this is the same approach used in the âPlaying a Videoâ guide):
@import "tailwindcss";
@import "@shelby-protocol/player/styles/neutral.css";Using shadcn/ui? Import @shelby-protocol/player/styles/shadcn.css instead
to match your theme.
If you donât want to import a player stylesheet, add the @source directive to your globals.css to allow Tailwind to scan the player package for class names:
@import "tailwindcss";
@source "../node_modules/@shelby-protocol/player";The @source directive tells Tailwind 4 to include classes used by the player
package. This is required for the player's utility classes to be generated.
Define Player Theme Colors
Add the sp-* color variables to your Tailwind theme. These colors are used for controls displayed over video content, so they should typically be light/white:
@theme inline {
/* ... your existing theme variables ... */
/* Shelby Player colors */
--color-sp-foreground: var(--sp-foreground);
--color-sp-accent: var(--sp-accent);
--color-sp-popover: var(--sp-popover);
--color-sp-popover-foreground: var(--sp-popover-foreground);
}Define CSS Variable Values
Add the actual color values to your :root and .dark selectors:
:root {
/* ... your existing variables ... */
/* Shelby Player - controls over video (use light colors) */
--sp-foreground: oklch(1 0 0); /* White - icons, text, seekbar */
--sp-accent: oklch(0.6 0.18 240); /* Your accent color - highlights */
--sp-popover: oklch(0.2 0 0 / 90%); /* Dark semi-transparent - menus */
--sp-popover-foreground: oklch(1 0 0); /* White - menu text */
}
.dark {
/* ... your existing variables ... */
/* Shelby Player - same as light mode (always over dark video) */
--sp-foreground: oklch(1 0 0);
--sp-accent: oklch(0.6 0.18 240);
--sp-popover: oklch(0.2 0 0 / 90%);
--sp-popover-foreground: oklch(1 0 0);
}Color Reference
| Variable | Usage | Recommended Value |
|---|---|---|
--sp-foreground | Control icons, seekbar track/progress, time display | White or light color |
--sp-accent | Active states, highlights, interstitial indicators | Your brand/primary color |
--sp-popover | Settings menu background | Dark with 80-90% opacity |
--sp-popover-foreground | Settings menu text | White or light color |
Important Notes
Why light colors? Player controls are always displayed over video content, which is typically dark. Using light colors ensures controls remain visible regardless of video content.
About shadcn.css: Importing
@shelby-protocol/player/styles/shadcn.css is the fastest way to match
shadcn/ui, but it includes its own :root and .dark variable definitions.
If youâd rather keep your app as the single source of truth for theming, use
neutral.css (or skip importing a player stylesheet) and define the sp-*
variables in your own CSS.
Complete Example
Here's a complete globals.css setup for a Next.js app with TailwindCSS 4:
@import "tailwindcss";
@import "tw-animate-css"; /* optional */
@source "../node_modules/@shelby-protocol/player";
@theme inline {
--color-sp-foreground: var(--sp-foreground);
--color-sp-accent: var(--sp-accent);
--color-sp-popover: var(--sp-popover);
--color-sp-popover-foreground: var(--sp-popover-foreground);
}
:root {
--sp-foreground: oklch(1 0 0);
--sp-accent: oklch(0.6 0.18 240);
--sp-popover: oklch(0.2 0 0 / 90%);
--sp-popover-foreground: oklch(1 0 0);
}
.dark {
--sp-foreground: oklch(1 0 0);
--sp-accent: oklch(0.6 0.18 240);
--sp-popover: oklch(0.2 0 0 / 90%);
--sp-popover-foreground: oklch(1 0 0);
}