sp-contextual-help

open

true

false

variant

Info

Help

label

offset

placement

top

top-start

top-end

right

right-start

right-end

bottom

bottom-start

bottom-end

left

left-start

left-end

NPM 1.7.0

View Storybook

Try it on Stackblitz

Overview

API

Changelog

Overview

An <sp-contextual-help> shows a user extra information about the state of either an adjacent component or an entire view. It explains a high-level topic about an experience and can point users to more information elsewhere.

View the design documentation for this component.

Usage

yarn add @spectrum-web-components/contextual-help

Import the side effectful registration of <sp-contextual-help> via:

import '@spectrum-web-components/contextual-help/sp-contextual-help.js';

When looking to leverage the ContextualHelp base class as a type and/or for extension purposes, do so via:

import { ContextualHelp } from '@spectrum-web-components/contextual-help';

Anatomy

Contextual help is a wrapper that attaches a popover to an icon-only action button.

It consists of the following parts:

Heading: assign the appropriate heading level to the heading slot to provide a title for the popover.
Content: text can be displayed within the popover by using the default slot.
Link: an optional <sp-link> can be assigned to the link slot per standalone link guidance.

Options

Variants

Information

The default variant is for in-line information using the "info" icon. Use the info icon for informative content: specific, brief, and contextual guidance. This is best for supplemental or nice-to-know information, in-line with a label or a component (if there is no label). The content should be instructive in tone.

<sp-contextual-help>
    <h2 slot="heading">Permission required</h2>
    Your admin must grant you permission before you can create a segment.
    <sp-link
        slot="link"
        href="https://opensource.adobe.com/spectrum-web-components/"
    >
        Request permission
    </sp-link>
</sp-contextual-help>

Help

Use variant="help" for helpful content: more detailed, in-depth guidance about a task, UI element, tool, or keyboard shortcuts. This may include an image, video, or link and should be helpful in tone.

<sp-contextual-help variant="help">
    <h2 slot="heading">What is a segment?</h2>
    Segments identify who your visitors are, what devices and services they use,
    where they navigate from, and much more.
    <sp-link
        slot="link"
        href="https://opensource.adobe.com/spectrum-web-components/"
    >
        Learn more about segments
    </sp-link>
</sp-contextual-help>

Placement

By default an <sp-contextual-help> will render its popover at the bottom-start position. This can be customized using the placement attribute and supports all the placement options an overlay-trigger component supports.

<sp-contextual-help placement="top-start">
    <h2 slot="heading">Permission required</h2>
    Your admin must grant you permission before you can create a segment.
    <sp-link
        slot="link"
        href="https://opensource.adobe.com/spectrum-web-components/"
    >
        Request permission
    </sp-link>
</sp-contextual-help>

Custom max width

Contextual help allows for a custom maximum width to be set using the --mod-spectrum-contextual-help-popover-maximum-width custom property.

Note: Maximum width should not be less than 100px.

<sp-contextual-help
    style="--mod-spectrum-contextual-help-popover-maximum-width: 200px;"
>
    <h2 slot="heading">Custom max width</h2>
    This is a test of the contextual help component with a custom max width of
    200px.
</sp-contextual-help>

Behaviors

<sp-contextual-help> does not fire any events of its own. You can listen, however, for the sp-open and sp-closed events which are fired when the popover opens or closes.

Accessibility

Given that the trigger is an icon-only <sp-action-button>, it is important to provide an accessible name for it, so that it can be properly announced by screen readers. By default, the <sp-contextual-help> uses an aria-label property with either "Information" or "Help" as values, depending on the component's variant. You can customize this using the label attribute.

When providing headings using the heading slot, make sure to provide actual heading elements such as h1, h2, h3 ... or use the role="heading" attribute.

Patch Changes

Updated dependencies [a646ae8, c1669d2]:
- @spectrum-web-components/overlay@1.7.0
- @spectrum-web-components/action-button@1.7.0
- @spectrum-web-components/popover@1.7.0
- @spectrum-web-components/dialog@1.7.0
- @spectrum-web-components/icons-workflow@1.7.0
- @spectrum-web-components/base@1.7.0

1.6.0

Patch Changes

Updated dependencies [03a4439, f6cebbd, 53f3769]:
- @spectrum-web-components/popover@1.6.0
- @spectrum-web-components/icons-workflow@1.6.0
- @spectrum-web-components/overlay@1.6.0
- @spectrum-web-components/dialog@1.6.0
- @spectrum-web-components/action-button@1.6.0
- @spectrum-web-components/base@1.6.0

1.5.0

Patch Changes

Updated dependencies [8f8735c, 6c58f50]:
- @spectrum-web-components/overlay@1.5.0
- @spectrum-web-components/action-button@1.5.0
- @spectrum-web-components/dialog@1.5.0
- @spectrum-web-components/popover@1.5.0
- @spectrum-web-components/icons-workflow@1.5.0
- @spectrum-web-components/base@1.5.0

1.4.0

Minor Changes

#5140 3cca7ea Thanks @TarunAdobe! - Contextual help now supports a custom maximum width to be set using the --mod-spectrum-contextual-help-popover-maximum-width custom property.

Patch Changes

Updated dependencies [72dbe62, 46cd782, 70f5f6f]:
- @spectrum-web-components/action-button@1.4.0
- @spectrum-web-components/overlay@1.4.0
- @spectrum-web-components/popover@1.4.0
- @spectrum-web-components/dialog@1.4.0
- @spectrum-web-components/icons-workflow@1.4.0
- @spectrum-web-components/base@1.4.0

1.3.0

Patch Changes

Updated dependencies [468314f]:
- @spectrum-web-components/dialog@1.3.0
- @spectrum-web-components/overlay@1.3.0
- @spectrum-web-components/popover@1.3.0
- @spectrum-web-components/action-button@1.3.0
- @spectrum-web-components/icons-workflow@1.3.0
- @spectrum-web-components/base@1.3.0

All notable changes to this project will be documented in this file. See Conventional Commits for commit guidelines.