Tooltips for icon-only controls; toggletips for help info

WordPress 7.1 comes with two new functions for rendering tool tips and informational help in core. Similar tool tips already exist in the editor, but were not available in the rest of the administration. This change brings improved accessibility for icon-only controls and situations where further explanation of a user interface element is needed.

Inf #55105, two new functions were added: wp_get_tooltip() and wp_get_toggletip().

The first function, wp_get_tooltip(), provides name visibility for buttons or links are otherwise only represented as icons. The second, wp_get_toggletip(), adds a button that can be triggered to view extended information about related controls.

In 7.1, each function has one relevant implementation. wp_get_tooltip() has been implemented on post meta box controls (move up, move down, and show/hide) to make those accessible names visible. wp_get_toggletip() has been added on the main login screen to provide an extended description of what the “Remember Me” checkbox does.

Enqueuing Required scripts and styles

The required CSS for tooltips is loaded globally, but the JavaScript is only loaded by default where post meta boxes are used and in the login screen.

You can enqueue required CSS on the front-end using:

wp_enqueue_style( 'wp-tooltip' );

You can enqueue required JavaScript as needed using:

wp_enqueue_script( 'wp-tooltip' );

Accessibility Notes

Both of these functions exist to provide support for gaps in accessibility support. It is always preferable for interface controls to have visible, persistent text labels, and it is also preferable to user interfaces to be structured so that additional help information is not required or is provided as visible descriptive text associated with the relevant input field.

However, we understand that space can be at a premium in complex web interfaces, and it is not always feasible to provide text labels for all controls. It is also a common case that explanatory text does not directly relate to one specific input, so that the aria-describedby solution is not practical. Using these functions can help make sure that the information provided for users is as accessible as possible within an interface that is imposing other limitations.

Tooltips

The function for adding tooltips is wp_get_tooltip(), and is only intended to provide visibility for controls that do not have a visible accessible name. For accessibility, it is still always the more accessible choice for a control to have persistently visible text.

Parameters for wp_get_tooltip()

• string $content Plain-text tool tip content.
• array $args An array of optional arguments for this tooltip.
  • string $id A unique ID for the popover element containing the tooltip. Default is a generated unique ID.
  • string $button Existing button or a markup. Used instead of a generated button.
  • string $label Unused for tool tips, but documented as part of the helper function.
  • string $close_label Unused for tool tips, but documented as part of the helper function.
  • string $icon A dashicons icon class for the toggle button. Default is dashicons-editor-help.
  • string $class Additional classes.

No additional arguments are required for wp_get_tooltip(); it will render a button with a tooltip control when only passed the $content argument. The $button parameter is available to make it easier to pass existing controls into the rendering button, and will be processed using the WP_HTML_Tag_Processor to add required attributes.

Parameters for wp_get_toggletip()

The function for adding information help text is intended for exposing additional help information.

• string $content Plain-text tool tip content.
• array $args An array of arguments for this tooltip.
  • string $id A unique ID for the popover element containing the tooltip. Default is a generated unique ID.
  • string $button Existing button or a markup. Used instead of a generated button.
  • string $label Accessible label for the toggle button. Default ‘Help’, matching the default icon. Ignored for tooltips.
  • string $close_label Accessible label for the close button. Default ‘Close’.
  • string $icon A dashicons icon class for the toggle button. Default is dashicons-editor-help.
  • string $class Additional classes.

Example Usages

Generate a button with a tooltip using a menu icon.

wp_get_tooltip(
    __( 'Show/Hide Menu', 'my-text-domain' ),
    array(
        'icon' => 'dashicons-menu',
    )
);

Output

<span class="wp-tooltip wp-is-tooltip">
    <button class="wp-tooltip__toggle" type="button" aria-label="Show/Hide Menu">
        <span class="dashicons dashicons-menu" aria-hidden="true"></span>
    </button>
    <span popover="hint" id="wp-tooltip-1" class="wp-tooltip__bubble" role="tooltip">
        <span id="wp-tooltip-1-text" class="wp-tooltip__text">Show/Hide Menu</span>
    </span>
</span>

Note: All generic markup uses span elements, to ensure that the control can be validly inserted inside any element. Using div or other sectioning elements would disallow usage within a paragraph.

Generate a button with a toggle tip.

wp_get_toggletip(
    __( 'Selecting "Remember Me" reduces the number of times you’ll be asked to log in using this device. To keep your account secure, use this option only on your personal devices.', 'my-text-domain' ),
    array(
        'id'    => 'rememberme-help-toggletip',
        'label' => 'Learn More',
        'icon'  => 'dashicons-welcome-learn-more',
    )
);

Output

<span class="wp-tooltip wp-is-toggletip">
    <button aria-haspopup="dialog" class="wp-tooltip__toggle" popovertarget="rememberme-help-toggletip" type="button" aria-label="Learn More">
        <span class="dashicons dashicons-welcome-learn-more" aria-hidden="true"></span>
    </button>
    <span popover="auto" id="rememberme-help-toggletip" class="wp-tooltip__bubble" role="dialog" aria-label="Learn More" tabindex="-1" autofocus="">
        <span id="rememberme-help-toggletip-text" class="wp-tooltip__text">Selecting "Remember Me" reduces the number of times you’ll be asked to log in using this device. To keep your account secure, use this option only on your personal devices.</span>
        <button type="button" class="wp-tooltip__close" popovertarget="rememberme-help-toggletip" popovertargetaction="hide" aria-label="Close">
            <span class="dashicons dashicons-no-alt" aria-hidden="true"></span>
        </button>
    </span>
</span>

Reviewed by @afercia

#7-1, #dev-notes