Effects · Gutenberg
Dark Mode Toggle block for WordPress
A light/dark mode switcher. Adds a toggle button that persists the user's theme preference to localStorage and applies a data attribute to the root element.
Get Blockenberg
Free Gutenberg block in Blockenberg. The inspector controls and front-end behavior on this page come from this block’s source, not a shared stub.
What it actually does
A light/dark mode switcher. Adds a toggle button that persists the user's theme preference to localStorage and applies a data attribute to the root element.
Inspector panels on this block: Appearance, Icons & Labels, Behaviour. Those titles come from index.js, not from a shared template.
Behavior controls: “Toggle Style” options: Switch (track + thumb), Icon Button; “Position” options: Inline (in flow), Floating (fixed corner); “Corner” options: Bottom Right, Bottom Left, Top Right, Top Left; “Default Theme” options: Light, Dark.
Where to find it
Gutenberg inserter → Effects → search “Dark Mode Toggle” (block name `blockenberg/dark-mode-toggle` in block.json). Style it in the sidebar after insert.
How to use Dark Mode Toggle block for WordPress
- Install Blockenberg. Install from WordPress.org and activate the plugin.
- Insert the block. Edit a page, click +, search for “Dark Mode Toggle”, insert it. Category: Effects.
- Configure inspector controls that exist on this block. Open Appearance. Set “Toggle Style”, “Position”, “Corner”, “Offset X (px)”.
- Check the published page. The view script reads HTML data attributes: data-attr, data-border-radius, data-button-size, data-dark-bg, data-dark-color, data-dark-icon, data-dark-label, data-dark-val. The block editor preview may not run the same view script.
Inspector controls from this block’s code
| Control | What the code does |
|---|---|
| Toggle Style | Select control; the chosen value is saved on the block. Options: Switch (track + thumb); Icon Button. block.json default: switch. Saved as `toggleStyle`. |
| Position | Select control; the chosen value is saved on the block. Options: Inline (in flow); Floating (fixed corner). block.json default: inline. Saved as `position`. |
| Corner | Select control; the chosen value is saved on the block. Options: Bottom Right; Bottom Left; Top Right; Top Left. block.json default: bottom-right. Saved as `floatCorner`. |
| Offset X (px) | Numeric range control in the inspector. Range 0–120. block.json default: 24. Saved as `floatOffsetX`. |
| Offset Y (px) | Numeric range control in the inspector. Range 0–120. block.json default: 24. Saved as `floatOffsetY`. |
| Button Size (px) | Numeric range control in the inspector. Range 28–80. block.json default: 44. Saved as `buttonSize`. |
| Border Radius (px) | Numeric range control in the inspector. Range 0–50. block.json default: 50. Saved as `borderRadius`. |
| Transition Duration (ms) | Numeric range control in the inspector. Range 0–1000. block.json default: 300. Saved as `transitionDuration`. |
| Show Icon | On/off toggle in the inspector. On by default. Saved as `showIcon`. |
| Show Label | On/off toggle in the inspector. Off by default. Saved as `showLabel`. |
| Hover Scale | On/off toggle in the inspector. On by default. Saved as `hoverScale`. |
| Drop Shadow | On/off toggle in the inspector. On by default. Saved as `shadow`. |
| Light Mode Icon | Text field in the inspector. block.json default: ☀️. Saved as `lightIcon`. |
| Dark Mode Icon | Text field in the inspector. block.json default: 🌙. Saved as `darkIcon`. |
| Light Label Text | Text field in the inspector. block.json default: Light. Saved as `lightLabel`. |
| Dark Label Text | Text field in the inspector. block.json default: Dark. Saved as `darkLabel`. |
| Default Theme | Select control; the chosen value is saved on the block. Options: Light; Dark. block.json default: light. Saved as `defaultTheme`. |
| Respect System Preference | On/off toggle in the inspector. If enabled, auto-applies dark mode when the OS is in dark mode (unless user overrides). On by default. Saved as `respectSystemPref`. |
| localStorage Key | Text field in the inspector. block.json default: bkdm-theme. Saved as `storageKey`. |
| HTML Attribute Name | Text field in the inspector. block.json default: data-theme. Saved as `dataAttribute`. |
| Dark Value | Text field in the inspector. block.json default: dark. Saved as `darkValue`. |
| Light Value | Text field in the inspector. block.json default: light. Saved as `lightValue`. |
| Label | Shared Blockenberg typography popover (family, size, weight, spacing). Saved as `typoLabel`. |
| Light Mode Background | Color control in the inspector. block.json default: #f3f4f6. Saved as `lightBg`. |
| Light Mode Icon/Text | Color control in the inspector. block.json default: #111827. Saved as `lightColor`. |
| Dark Mode Background | Color control in the inspector. block.json default: #1f2937. Saved as `darkBg`. |
| Dark Mode Icon/Text | Color control in the inspector. block.json default: #f9fafb. Saved as `darkColor`. |
| Switch Track (Light) | Color control in the inspector. block.json default: #d1d5db. Saved as `switchTrackLight`. |
| Switch Track (Dark) | Color control in the inspector. block.json default: #4f46e5. Saved as `switchTrackDark`. |
| Switch Thumb | Color control in the inspector. block.json default: #ffffff. Saved as `switchThumbColor`. |
What the front-end script actually does
- The view script reads HTML data attributes: data-attr, data-border-radius, data-button-size, data-dark-bg, data-dark-color, data-dark-icon, data-dark-label, data-dark-val.
- It writes to localStorage in the visitor’s browser, not to wp_options.
When this is the right block
- A light/dark mode switcher. Adds a toggle button that persists the user's theme preference to localStorage and applies a data attribute to the root element — that is the job of Dark Mode Toggle, not a generic content block.
- Use it when you need the editor control labeled “Toggle Style”, which exists on this block’s inspector.
- It matches pages about dark mode, light mode, theme.
- Inserter grouping: motion, overlays, and visual treatments.
Notes from the implementation
viewScript: this folder’s frontend.js is enqueued on the front end for this block.
FAQ
How do I add the Dark Mode Toggle block in WordPress?
Install Blockenberg from WordPress.org, edit a page in the block editor, click +, and search for “Dark Mode Toggle”. It sits under Effects. After insert, open Appearance and set “Toggle Style”, “Position”, “Corner”, “Offset X (px)”.
Where does Dark Mode Toggle store visitor state?
In localStorage on that browser. Clearing site data resets it. It is not a WordPress user meta field unless render.php says so.
Is the Dark Mode Toggle Gutenberg block free?
Yes. Dark Mode Toggle ships inside Blockenberg. Get the plugin from WordPress.org — no paid add-on is required for this block.
Can I style Dark Mode Toggle to match my theme?
Yes. Blockenberg’s shared typography and color panels apply here, plus any block-specific style controls listed on this page (panels: Appearance, Icons & Labels, Behaviour).
Related effects blocks
Unfold
Expandable content section that starts collapsed with a fade gradient and expands smoothly on button click.
3D Text
Eye-catching 3D extruded text using CSS text-shadow layers and perspective transforms. Supports rotate-on-hover, float animation, and customizable depth, colors and typography.
Animated Text
Heading with animated cycling words — typewriter, fade, slide, or flip effects. Perfect for hero sections.
Card Carousel
Horizontal drag-to-scroll card carousel with rich cards, autoplay, arrows, dots, and responsive column settings.
Card Deck Slider
A 3D card deck slider where cards arc/fan out behind the front card and animate through the sequence.
Card Stack
A fanned or stacked pile of cards with hover-spread interaction. Perfect for testimonials, case studies, or feature highlights.
Get Blockenberg
Install Blockenberg from WordPress.org, then insert Dark Mode Toggle from the Gutenberg inserter.