Configuring the Fullscreen Plugin

Basic Usage

Default Configuration

The plugin works out of the box with sensible defaults:

import { pluginFullscreen } from 'expressive-code-fullscreen';

export default {
  plugins: [
    pluginFullscreen(), // Uses all default options.
  ],
};

Configuration Options

Core Options

Option	Type	Default	Description
`enabled`	`boolean`	`true`	Enable/disable the plugin
`fullscreenButtonTooltip`	`string`	`'Toggle fullscreen view'`	Tooltip text for the fullscreen button
`enableEscapeKey`	`boolean`	`true`	Allow Escape key to exit fullscreen
`exitOnBrowserBack`	`boolean`	`true`	Exit fullscreen when browser back button is pressed
`addToUntitledBlocks`	`boolean`	`true`	Add fullscreen button to code blocks without titles
`showOnHoverOnly`	`boolean`	`true`	Show fullscreen button only on hover for untitled, non-terminal blocks
`animationDuration`	`number`	`200`	Animation duration in milliseconds
`svgPathFullscreenOn`	`string`	Default expand icon	SVG path for the enter fullscreen icon
`svgPathFullscreenOff`	`string`	Default compress icon	SVG path for the exit fullscreen icon

Custom Configuration

You can customize the plugin behavior by passing an options object to pluginFullscreen():

import { pluginFullscreen } from 'expressive-code-fullscreen';

export default defineEcConfig({
  plugins: [
    pluginFullscreen({
      enabled: true,
      fullscreenButtonTooltip: 'View in fullscreen',
      enableEscapeKey: true,
      exitOnBrowserBack: true,
      addToUntitledBlocks: true,
      showOnHoverOnly: true,
      animationDuration: 300,
      svgPathFullscreenOn: 'M16 3h6v6h-2V5h-4V3zM2 3h6v2H4v4H2V3zm18 16v-4h2v6h-6v-2h4zM4 19h4v2H2v-6h2v4z',
      svgPathFullscreenOff: 'M18 7h4v2h-6V3h2v4zM8 9H2V7h4V3h2v6zm10 8v4h-2v-6h6v2h-4zM8 15v6H6v-4H2v-2h6z',
    }),
  ],
});

Custom SVG Icons

You can customize the fullscreen toggle icons:

pluginFullscreen({
  svgPathFullscreenOn: 'M16 3h6v6h-2V5h-4V3zM2 3h6v2H4v4H2V3zm18 16v-4h2v6h-6v-2h4zM4 19h4v2H2v-6h2v4z',
  svgPathFullscreenOff: 'M18 7h4v2h-6V3h2v4zM8 9H2V7h4V3h2v6zm10 8v4h-2v-6h6v2h-4zM8 15v6H6v-4H2v-2h6z',
})

Examples

Production Configuration

pluginFullscreen({
  enabled: true,
  fullscreenButtonTooltip: 'View code in fullscreen',
  enableEscapeKey: true,
  exitOnBrowserBack: true,
  animationDuration: 250,
})

Disable for Untitled Blocks

pluginFullscreen({
  addToUntitledBlocks: false, // Only show on blocks with titles.
})

Always Show Button (Disable Hover-Only)

pluginFullscreen({
  showOnHoverOnly: false, // Always show button on untitled blocks.
})

The fullscreen button will appear in the top-right corner of your code blocks, providing users with an enhanced viewing experience for longer code snippets.

Fullscreen Plugin Theming System

You can override the default styles in your Expressive Code config using the styleOverrides.fullscreen object if you want to change the colors, fonts, or other styles of the fullscreen plugin.

Available Theme Options

toolbarBg: Background color of the font controls toolbar
- Default: 'rgba(90, 88, 88, 0.95)'
- Example: 'rgba(30, 30, 30, 0.95)', '#2d2d2d'
toolbarBorder: Border color around the toolbar
- Default: 'rgba(255, 255, 255, 0.1)'
- Example: 'rgba(100, 149, 237, 0.3)', 'transparent'

Button Styling

buttonBg: Default background color of toolbar buttons
- Default: 'rgba(58, 57, 57, 0.9)'
buttonBgHover: Background color when hovering over buttons
- Default: 'rgba(120, 120, 120, 0.5)'
buttonBgActive: Background color when buttons are pressed
- Default: 'rgba(25, 25, 25, 0.9)'
buttonText: Text/icon color for buttons
- Default: '#ffffff'
buttonBorder: Border color for buttons
- Default: 'rgba(255, 255, 255, 0.2)'
buttonFocus: Focus outline color for accessibility
- Default: 'rgba(74, 144, 226, 0.6)'

Container & Effects

containerBg: Background color of the fullscreen overlay
- Default: 'rgba(0, 0, 0, 0.85)'
contentShadow: Shadow color for elevated elements
- Default: 'rgba(0, 0, 0, 0.5)'

Hints & Tooltips

hintBg: Background color for hint messages and tooltips
- Default: 'rgba(20, 20, 20, 0.95)'
hintText: Text color for hints and tooltips
- Default: '#ffffff'
hintBorder: Border color for hint elements
- Default: 'rgba(255, 255, 255, 0.2)'

Quick Start

{
  plugins: [pluginFullscreen()],
  styleOverrides: {
    fullscreen: {
      toolbarBg: 'rgba(30, 30, 30, 0.95)',
      buttonBg: 'rgba(20, 20, 20, 0.9)',
      buttonBgHover: 'rgba(45, 45, 45, 0.9)',
      buttonText: '#e0e0e0',
      // ... other theme options
    }
  }
}

Complete Theme Configuration Example

Here’s a complete example showing all available theme options with their default values:

{
  plugins: [pluginFullscreen()],
  styleOverrides: {
    fullscreen: {
      // Toolbar styling.
      toolbarBg: 'rgba(90, 88, 88, 0.95)',
      toolbarBorder: 'rgba(255, 255, 255, 0.1)',

      // Button styling.
      buttonBg: 'rgba(58, 57, 57, 0.9)',
      buttonBgHover: 'rgba(120, 120, 120, 0.5)',
      buttonBgActive: 'rgba(25, 25, 25, 0.9)',
      buttonText: '#ffffff',
      buttonBorder: 'rgba(255, 255, 255, 0.2)',
      buttonFocus: 'rgba(74, 144, 226, 0.6)',

      // Container and effects.
      containerBg: 'rgba(0, 0, 0, 0.85)',
      contentShadow: 'rgba(0, 0, 0, 0.5)',

      // Hints and tooltips.
      hintBg: 'rgba(20, 20, 20, 0.95)',
      hintText: '#ffffff',
      hintBorder: 'rgba(255, 255, 255, 0.2)',
    }
  }
}

Custom Theme Example

{
  plugins: [pluginFullscreen()],
  styleOverrides: {
    fullscreen: {
      // Dark blue theme.
      toolbarBg: 'rgba(25, 39, 52, 0.95)',
      toolbarBorder: 'rgba(100, 149, 237, 0.3)',
      buttonBg: 'rgba(15, 29, 42, 0.9)',
      buttonBgHover: 'rgba(35, 49, 62, 0.9)',
      buttonBgActive: 'rgba(5, 19, 32, 0.9)',
      buttonText: '#e6f3ff',
      buttonBorder: 'rgba(100, 149, 237, 0.4)',
      buttonFocus: 'rgba(100, 149, 237, 0.8)',
      containerBg: 'rgba(10, 25, 41, 0.9)',
      contentShadow: 'rgba(0, 20, 40, 0.6)',
      hintBg: 'rgba(15, 29, 42, 0.95)',
      hintText: '#e6f3ff',
      hintBorder: 'rgba(100, 149, 237, 0.3)',
    }
  }
}