Customizing the Theme

The EmbedPDF viewer snippet includes a robust theming system that supports Light, Dark, and System modes. You can customize every color aspect of the viewer—from backgrounds and borders to brand accents—by passing a theme object during initialization.

Basic Configuration

To set the initial color mode, use the preference property within the theme configuration.


const viewer = EmbedPDF.init({
  // ... other config
  theme: {
    // Options: 'light', 'dark', or 'system' (default)
    preference: 'dark' 
  }
});

Overriding Colors

You can override specific colors for both light and dark modes. You do not need to provide a full theme; the viewer performs a deep merge, so you only need to specify the values you want to change.

Example: Custom Brand Color

To change the primary blue accent to your brand color (e.g., Purple) for both light and dark modes:


const viewer = EmbedPDF.init({
  // ...
  theme: {
    preference: 'system',
    light: {
      accent: {
        primary: '#9333ea',        // Main brand color
        primaryHover: '#7e22ce',   // Hover state
        primaryActive: '#6b21a8',  // Click state
        primaryLight: '#f3e8ff',   // Subtle backgrounds (e.g., selection)
        primaryForeground: '#fff'  // Text on top of primary color
      }
    },
    dark: {
      accent: {
        primary: '#a855f7',        // Lighter purple for dark mode
        primaryHover: '#9333ea',
        // ... other states
      }
    }
  }
});

Interactive Example

Click on a color below to see the viewer update its accent color in real-time. The viewer also syncs with the website’s light/dark mode:

Choose brand color:

Selected: Purple

Theme Structure

The theme object is divided into semantic categories. Here is the structure you can override:

1. Accent (Branding)

Controls the main call-to-action buttons, active states, and focus rings.


accent: {
  primary: string;           // Main brand color
  primaryHover: string;      // Hover state
  primaryActive: string;     // Active/Pressed state
  primaryLight: string;      // Very light tint (used for selections)
  primaryForeground: string; // Text color on top of primary button
}

2. Backgrounds

Controls the layers of the application.


background: {
  app: string;         // The main background behind the document
  surface: string;     // Toolbars, sidebars, panels
  surfaceAlt: string;  // Secondary toolbars
  elevated: string;    // Dropdowns, popups
  overlay: string;     // Modal backdrops (usually transparent rgba)
  input: string;       // Text inputs and checkboxes
}

3. Foreground (Text)

Controls text colors.


foreground: {
  primary: string;     // Headings, main body text
  secondary: string;   // Labels, less important text
  muted: string;       // Placeholders, disabled-looking text
  disabled: string;    // Actually disabled elements
  onAccent: string;    // Text on top of accent colors
}

4. Interactive

Controls generic hover and selection states.


interactive: {
  hover: string;       // Hover background for standard buttons
  active: string;      // Click background
  selected: string;    // Selected item background (e.g. active tool)
  focus: string;       // Focus ring outline color
}

5. Borders


border: {
  default: string;     // Standard inputs, dividers
  subtle: string;      // Very light dividers
  strong: string;      // Active inputs, emphasis
}

6. Semantic States

Used for alerts, success messages, and warnings.


state: {
  error: string;
  errorLight: string; // Background for error messages
  warning: string;
  warningLight: string;
  success: string;
  successLight: string;
  info: string;
  infoLight: string;
}

Changing Themes at Runtime

You can update the theme dynamically after the viewer has initialized using the .setTheme() method on the viewer instance.


const viewer = EmbedPDF.init({ ... });
 
// 1. Switch mode
document.getElementById('toggle-btn').onclick = () => {
  const current = viewer.themePreference;
  viewer.setTheme(current === 'light' ? 'dark' : 'light');
};
 
// 2. Update colors dynamically
viewer.setTheme({
  preference: 'light',
  light: {
    background: { app: '#ffcccc' } // Change app background to red
  }
});

Event Listening

You can listen for theme changes to sync your own UI with the viewer.


viewer.addEventListener('themechange', (e) => {
  console.log('New Color Scheme:', e.detail.colorScheme); // 'light' | 'dark'
  console.log('Active Theme Object:', e.detail.theme);
});