[wp-trac] [WordPress Trac] #65029: Add Keyboard Shortcut to Hide and Show Toolbar on Frontend (was: Trac Ticket: Keyboard Shortcut to Toggle Toolbar on Frontend)

Tue Apr 7 15:05:25 UTC 2026

#65029: Add Keyboard Shortcut to Hide and Show Toolbar on Frontend
-------------------------+------------------------------
 Reporter:  apermo       |       Owner:  (none)
     Type:  enhancement  |      Status:  new
 Priority:  normal       |   Milestone:  Awaiting Review
Component:  Toolbar      |     Version:
 Severity:  normal       |  Resolution:
 Keywords:  has-patch    |     Focuses:  accessibility
-------------------------+------------------------------
Changes (by sabernhardt):

 * focuses:   => accessibility

Old description:

> Add a keyboard shortcut (access+w) to temporarily hide and show the
> toolbar on the frontend. This gives logged-in users a quick way to
> preview their site without the toolbar, without navigating to Profile
> settings or logging out.
>
> Description
>
> When working on a site's frontend, the toolbar covers the top 32px (46px
> on mobile) of the page. Designers, content editors, and developers
> frequently need to see the page without it — for screenshots, visual
> testing, or checking how fixed headers behave. Today the only options
> are:
>
> 1. Uncheck "Show Toolbar when viewing site" in the user profile (requires
> a page reload)
> 2. Use show_admin_bar( false ) in code (requires a code change and
> reload)
> 3. Use browser DevTools to hide the element manually
> 4. Install a plugin (e.g. https://wordpress.org/plugins/apermo-adminbar-
> toggle/)
>
> None of these are fast or convenient for a quick toggle.
>
> Proposed Solution
>
> A keyboard shortcut using the WordPress access modifier pattern:
>
> - Windows/Linux: Alt+Shift+W
> - Mac: Ctrl+Option+W
>
> The "W" key is mnemonic for "WordPress toolbar." This follows the same
> modifier pattern used by all existing WordPress keyboard shortcuts (e.g.
> access+h for help, access+d for strikethrough), ensuring consistency.
>
> Behavior
>
> - Toggle only: The shortcut hides the toolbar; pressing it again brings
> it back.
> - No persistence: The state resets on page navigation. This is
> intentional — the feature is for quick previews, not a permanent setting.
> - Frontend only: The shortcut does not work in wp-admin, where the
> toolbar is part of the fixed layout and is not optional by design (see
> #19685).
> - Smooth animation: The toolbar slides up/down with a 200ms CSS
> transition.
> - Page spacing adjusts: The --wp-admin--admin-bar--height custom property
> is set to 0px when hidden, so scroll-padding-top and the bump margin-top
> adjust automatically. No content jump.
> - Accessible: An aria-live region announces "Toolbar hidden." / "Toolbar
> visible." for screen reader users. The toolbar element gets aria-
> hidden="true" when hidden.
>
> Shortcut Conflict Analysis
>
> The access+w shortcut was chosen after an audit of all existing
> shortcuts:
>
> WordPress: The letter w is completely free in both the classic editor and
> block editor access modifier space. No WordPress core shortcut uses
> access+w.
>
> Browsers: Alt+Shift+W / Ctrl+Option+W has no known conflicts in Chrome,
> Firefox, Safari, or Edge on any platform. (By contrast, access+b — "B for
> Bar" — conflicts with Chrome/Edge's "focus bookmarks bar" on
> Windows/Linux.)
>
> Historical note: WordPress previously used Alt+Shift+W for "Distraction
> Free Writing" mode, which was removed years ago. The association with
> "toggling a UI element for focus" is fitting.
>
> Prior Art
>
> - In 2016 I released a plugin, that never good notable attention with the
> feature https://wordpress.org/plugins/apermo-adminbar/ and
> https://wordpress.org/plugins/apermo-adminbar-toggle/
> - #53184 discusses auto-hiding the toolbar but does not propose a
> keyboard shortcut.
> - No existing Trac ticket specifically requests a keyboard shortcut to
> toggle the toolbar.
>
> Implementation
>
> The patch modifies three files:
>
> 1. src/js/_enqueues/lib/admin-bar.js — Adds a keydown listener for
> access+w (frontend only), a toggleToolbar() function that toggles the wp-
> toolbar-hidden class on <html>, and screen reader announcements via a
> live region.
> 2. src/wp-includes/css/admin-bar.css — Adds the html.wp-toolbar-hidden
> rules: sets --wp-admin--admin-bar--height: 0px, overrides the bump
> margin-top, and uses transform: translateY(-100%) with visibility: hidden
> to slide the bar out.
> 3. src/wp-includes/class-wp-admin-bar.php — Adds wp_localize_script for
> the two screen reader strings (toolbarHidden, toolbarVisible).
>
> Theme Compatibility
>
> Themes that use var(--wp-admin--admin-bar--height) for their toolbar
> offset will adjust automatically. Themes that hardcode a 32px top offset
> based on the .admin-bar body class will not adjust, but this is the same
> limitation that exists when users disable the toolbar via Profile
> settings today.
>
> Themes can also use the html.wp-toolbar-hidden selector to apply custom
> styles when the toolbar is hidden.

New description:

 Add a keyboard shortcut (`access+w`) to temporarily hide and show the
 toolbar on the frontend. This gives logged-in users a quick way to preview
 their site without the toolbar, without navigating to Profile settings or
 logging out.

 ==== Description

 When working on a site's frontend, the toolbar covers the top 32px (46px
 on mobile) of the page. Designers, content editors, and developers
 frequently need to see the page without it — for screenshots, visual
 testing, or checking how fixed headers behave. Today the only options are:

 1. Uncheck "Show Toolbar when viewing site" in the user profile (requires
 a page reload)
 2. Use `show_admin_bar( false )` in code (requires a code change and
 reload)
 3. Use browser DevTools to hide the element manually
 4. Install a plugin (e.g. https://wordpress.org/plugins/apermo-adminbar-
 toggle/)

 None of these are fast or convenient for a quick toggle.

 ==== Proposed Solution

 A keyboard shortcut using the WordPress access modifier pattern:

 - Windows/Linux: `Alt+Shift+W`
 - Mac: `Ctrl+Option+W`

 The "W" key is mnemonic for "WordPress toolbar." This follows the same
 modifier pattern used by all existing WordPress keyboard shortcuts (e.g.
 `access+h` for help, `access+d` for strikethrough), ensuring consistency.

 ===== Behavior

 - Toggle only: The shortcut hides the toolbar; pressing it again brings it
 back.
 - No persistence: The state resets on page navigation. This is intentional
 — the feature is for quick previews, not a permanent setting.
 - Frontend only: The shortcut does not work in `wp-admin`, where the
 toolbar is part of the fixed layout and is not optional by design (see
 #19685).
 - Smooth animation: The toolbar slides up/down with a 200ms CSS
 transition.
 - Page spacing adjusts: The `--wp-admin--admin-bar--height` custom
 property is set to `0px` when hidden, so `scroll-padding-top` and the bump
 `margin-top` adjust automatically. No content jump.
 - Accessible: An `aria-live` region announces "Toolbar hidden." / "Toolbar
 visible." for screen reader users. The toolbar element gets `aria-
 hidden="true"` when hidden.

 ==== Shortcut Conflict Analysis

 The `access+w` shortcut was chosen after an audit of all existing
 shortcuts:

 WordPress: The letter w is completely free in both the classic editor and
 block editor access modifier space. No WordPress core shortcut uses
 `access+w`.

 Browsers: `Alt+Shift+W `/ `Ctrl+Option+W` has no known conflicts in
 Chrome, Firefox, Safari, or Edge on any platform. (By contrast, `access+b`
 — "B for Bar" — conflicts with Chrome/Edge's "focus bookmarks bar" on
 Windows/Linux.)

 Historical note: WordPress previously used `Alt+Shift+W` for "Distraction
 Free Writing" mode, which was removed years ago. The association with
 "toggling a UI element for focus" is fitting.

 ==== Prior Art

 - In 2016 I released a plugin, that never got notable attention with the
 feature https://wordpress.org/plugins/apermo-adminbar/ and
 https://wordpress.org/plugins/apermo-adminbar-toggle/
 - #53184 discusses auto-hiding the toolbar but does not propose a keyboard
 shortcut.
 - No existing Trac ticket specifically requests a keyboard shortcut to
 toggle the toolbar.

 ==== Implementation

 The patch modifies three files:

 1. `src/js/_enqueues/lib/admin-bar.js` — Adds a `keydown` listener for
 `access+w` (frontend only), a `toggleToolbar()` function that toggles the
 `wp-toolbar-hidden` class on `<html>`, and screen reader announcements via
 a live region.
 2. `src/wp-includes/css/admin-bar.css` — Adds the `html.wp-toolbar-hidden`
 rules: sets `--wp-admin--admin-bar--height: 0px`, overrides the bump
 `margin-top`, and uses `transform: translateY(-100%)` with `visibility:
 hidden` to slide the bar out.
 3. `src/wp-includes/class-wp-admin-bar.php` — Adds `wp_localize_script`
 for the two screen reader strings (`toolbarHidden`, `toolbarVisible`).

 ==== Theme Compatibility

 Themes that use `var(--wp-admin--admin-bar--height)` for their toolbar
 offset will adjust automatically. Themes that hardcode a `32px` top offset
 based on the `.admin-bar` body class will not adjust, but this is the same
 limitation that exists when users disable the toolbar via Profile settings
 today.

 Themes can also use the `html.wp-toolbar-hidden` selector to apply custom
 styles when the toolbar is hidden.

--

-- 
Ticket URL: <https://core.trac.wordpress.org/ticket/65029#comment:3>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform