ContextualHelp
Contextual help shows a user extra information about the state of an adjacent component, or a total view.
install | yarn add @adobe/react-spectrum |
---|---|
added | 3.16.0 |
usage | import {ContextualHelp} from '@adobe/react-spectrum' |
Example#
<ContextualHelp variant="info">
<Heading>Need help?</Heading>
<Content>
<Text>
If you're having issues accessing your account, contact our customer
support team for help.
</Text>
</Content>
</ContextualHelp>
<ContextualHelp variant="info">
<Heading>Need help?</Heading>
<Content>
<Text>
If you're having issues accessing your account,
contact our customer support team for help.
</Text>
</Content>
</ContextualHelp>
<ContextualHelp variant="info">
<Heading>
Need help?
</Heading>
<Content>
<Text>
If you're having
issues accessing
your account,
contact our
customer support
team for help.
</Text>
</Content>
</ContextualHelp>
Content#
Unlike Dialog, the layout in ContextualHelp is very deliberate. Every ContextualHelp component is triggered as a popover where the
trigger element is a quiet action button with either a help or info icon. Much like Dialog, however, ContextualHelp has sections that
can be populated by providing the following components to your ContextualHelp as children:
Heading (title), Content (body), and Footer (link).
Each of these components are required in a Spectrum compliant ContextualHelp except for Footer
since including a link is optional.
<ContextualHelp variant="help">
<Heading>What is a segment?</Heading>
<Content>
<Text>
Segments identify who your visitors are, what devices and services they
use, where they navigated from, and much more.
</Text>
</Content>
<Footer>
<Link>Learn more about segments</Link>
</Footer>
</ContextualHelp>
<ContextualHelp variant="help">
<Heading>What is a segment?</Heading>
<Content>
<Text>
Segments identify who your visitors are, what
devices and services they use, where they navigated
from, and much more.
</Text>
</Content>
<Footer>
<Link>Learn more about segments</Link>
</Footer>
</ContextualHelp>
<ContextualHelp variant="help">
<Heading>
What is a segment?
</Heading>
<Content>
<Text>
Segments identify
who your visitors
are, what devices
and services they
use, where they
navigated from,
and much more.
</Text>
</Content>
<Footer>
<Link>
Learn more about
segments
</Link>
</Footer>
</ContextualHelp>
Placement#
ContextualHelp supports Dialog placement options for when the positioning of the popover needs to customized.
<ContextualHelp variant="info" placement="top start">
<Heading>Placement</Heading>
<Content>
<Text>
The placement of this contextual help popover has been customized to use
top start.
</Text>
</Content>
</ContextualHelp>
<ContextualHelp variant="info" placement="top start">
<Heading>Placement</Heading>
<Content>
<Text>
The placement of this contextual help popover has
been customized to use top start.
</Text>
</Content>
</ContextualHelp>
<ContextualHelp
variant="info"
placement="top start"
>
<Heading>
Placement
</Heading>
<Content>
<Text>
The placement of
this contextual
help popover has
been customized
to use top start.
</Text>
</Content>
</ContextualHelp>
Events#
ContextualHelp accepts an onOpenChange
prop, triggered when the ContextualHelp's popover opens or closes.
The example below uses onOpenChange
to update a separate element with the current open state of the Dialog.
function Example() {
let [state, setState] = React.useState(false);
return (
<Flex alignItems="center" gap="size-100">
<ContextualHelp
variant="info"
onOpenChange={(isOpen) => setState(isOpen)}
>
<Heading>Permission required</Heading>
<Content>
<Text>
Your admin must grant you permission before you can create a
segment.
</Text>
</Content>
</ContextualHelp>
<Text>Current open state: {state.toString()}</Text>
</Flex>
);
}
function Example() {
let [state, setState] = React.useState(false);
return (
<Flex alignItems="center" gap="size-100">
<ContextualHelp
variant="info"
onOpenChange={(isOpen) => setState(isOpen)}
>
<Heading>Permission required</Heading>
<Content>
<Text>
Your admin must grant you permission before you
can create a segment.
</Text>
</Content>
</ContextualHelp>
<Text>Current open state: {state.toString()}</Text>
</Flex>
);
}
function Example() {
let [state, setState] =
React.useState(
false
);
return (
<Flex
alignItems="center"
gap="size-100"
>
<ContextualHelp
variant="info"
onOpenChange={(
isOpen
) =>
setState(
isOpen
)}
>
<Heading>
Permission
required
</Heading>
<Content>
<Text>
Your admin
must grant
you
permission
before you
can create a
segment.
</Text>
</Content>
</ContextualHelp>
<Text>
Current open
state:{' '}
{state
.toString()}
</Text>
</Flex>
);
}
Props#
Name | Type | Default | Description |
children | ReactNode | — | Contents of the Contextual Help popover. |
variant | 'help' | 'info' | 'help' | Indicates whether contents are informative or provides helpful guidance. |
placement | Placement | 'bottom start' | The placement of the popover with respect to the action button. |
isOpen | boolean | — | Whether the overlay is open by default (controlled). |
defaultOpen | boolean | — | Whether the overlay is open by default (uncontrolled). |
containerPadding | number | 12 | The placement padding that should be applied between the element and its surrounding container. |
offset | number | 0 | The additional offset applied along the main axis between the element and its anchor element. |
crossOffset | number | 0 | The additional offset applied along the cross axis between the element and its anchor element. |
shouldFlip | boolean | true | Whether the element should flip its orientation (e.g. top to bottom or left to right) when there is insufficient room for it to render completely. |
Events
Name | Type | Description |
onOpenChange | (
(isOpen: boolean
)) => void | Handler that is called when the overlay's open state changes. |
Layout
Name | Type | Description |
flex | Responsive<string
| number
| boolean> | When used in a flex layout, specifies how the element will grow or shrink to fit the space available. See MDN. |
flexGrow | Responsive<number> | When used in a flex layout, specifies how the element will grow to fit the space available. See MDN. |
flexShrink | Responsive<number> | When used in a flex layout, specifies how the element will shrink to fit the space available. See MDN. |
flexBasis | Responsive<number | string> | When used in a flex layout, specifies the initial main size of the element. See MDN. |
alignSelf | Responsive<'auto'
| 'normal'
| 'start'
| 'end'
| 'center'
| 'flex-start'
| 'flex-end'
| 'self-start'
| 'self-end'
| 'stretch'> | Overrides the alignItems property of a flex or grid container. See MDN. |
justifySelf | Responsive<'auto'
| 'normal'
| 'start'
| 'end'
| 'flex-start'
| 'flex-end'
| 'self-start'
| 'self-end'
| 'center'
| 'left'
| 'right'
| 'stretch'> | Specifies how the element is justified inside a flex or grid container. See MDN. |
order | Responsive<number> | The layout order for the element within a flex or grid container. See MDN. |
gridArea | Responsive<string> | When used in a grid layout, specifies the named grid area that the element should be placed in within the grid. See MDN. |
gridColumn | Responsive<string> | When used in a grid layout, specifies the column the element should be placed in within the grid. See MDN. |
gridRow | Responsive<string> | When used in a grid layout, specifies the row the element should be placed in within the grid. See MDN. |
gridColumnStart | Responsive<string> | When used in a grid layout, specifies the starting column to span within the grid. See MDN. |
gridColumnEnd | Responsive<string> | When used in a grid layout, specifies the ending column to span within the grid. See MDN. |
gridRowStart | Responsive<string> | When used in a grid layout, specifies the starting row to span within the grid. See MDN. |
gridRowEnd | Responsive<string> | When used in a grid layout, specifies the ending row to span within the grid. See MDN. |
Spacing
Name | Type | Description |
margin | Responsive<DimensionValue> | The margin for all four sides of the element. See MDN. |
marginTop | Responsive<DimensionValue> | The margin for the top side of the element. See MDN. |
marginBottom | Responsive<DimensionValue> | The margin for the bottom side of the element. See MDN. |
marginStart | Responsive<DimensionValue> | The margin for the logical start side of the element, depending on layout direction. See MDN. |
marginEnd | Responsive<DimensionValue> | The margin for the logical end side of an element, depending on layout direction. See MDN. |
marginX | Responsive<DimensionValue> | The margin for both the left and right sides of the element. See MDN. |
marginY | Responsive<DimensionValue> | The margin for both the top and bottom sides of the element. See MDN. |
Sizing
Name | Type | Description |
width | Responsive<DimensionValue> | The width of the element. See MDN. |
minWidth | Responsive<DimensionValue> | The minimum width of the element. See MDN. |
maxWidth | Responsive<DimensionValue> | The maximum width of the element. See MDN. |
height | Responsive<DimensionValue> | The height of the element. See MDN. |
minHeight | Responsive<DimensionValue> | The minimum height of the element. See MDN. |
maxHeight | Responsive<DimensionValue> | The maximum height of the element. See MDN. |
Positioning
Name | Type | Description |
position | Responsive<'static'
| 'relative'
| 'absolute'
| 'fixed'
| 'sticky'> | Specifies how the element is positioned. See MDN. |
top | Responsive<DimensionValue> | The top position for the element. See MDN. |
bottom | Responsive<DimensionValue> | The bottom position for the element. See MDN. |
left | Responsive<DimensionValue> | The left position for the element. See MDN. Consider using start instead for RTL support. |
right | Responsive<DimensionValue> | The right position for the element. See MDN. Consider using start instead for RTL support. |
start | Responsive<DimensionValue> | The logical start position for the element, depending on layout direction. See MDN. |
end | Responsive<DimensionValue> | The logical end position for the element, depending on layout direction. See MDN. |
zIndex | Responsive<number> | The stacking order for the element. See MDN. |
isHidden | Responsive<boolean> | Hides the element. |
Accessibility
Name | Type | Description |
id | string | The element's unique identifier. See MDN. |
aria-label | string | Defines a string value that labels the current element. |
aria-labelledby | string | Identifies the element (or elements) that labels the current element. |
aria-describedby | string | Identifies the element (or elements) that describes the object. |
aria-details | string | Identifies the element (or elements) that provide a detailed, extended description for the object. |
Advanced
Name | Type | Description |
UNSAFE_className | string | Sets the CSS className for the element. Only use as a last resort. Use style props instead. |
UNSAFE_style | CSSProperties | Sets inline style for the element. Only use as a last resort. Use style props instead. |
Visual options#
Info#
Use the info icon for brief, specific, 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 for an info icon’s popover should be instructive in tone.
<ContextualHelp variant="info">
<Heading>Permission required</Heading>
<Content>
<Text>
Your admin must grant you permission before you can create a segment.
</Text>
</Content>
</ContextualHelp>
<ContextualHelp variant="info">
<Heading>Permission required</Heading>
<Content>
<Text>
Your admin must grant you permission before you can
create a segment.
</Text>
</Content>
</ContextualHelp>
<ContextualHelp variant="info">
<Heading>
Permission required
</Heading>
<Content>
<Text>
Your admin must
grant you
permission before
you can create a
segment.
</Text>
</Content>
</ContextualHelp>
Help#
Use the help icon for content that offers 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.
<ContextualHelp variant="help">
<Heading>What is a segment?</Heading>
<Content>
<Text>
Segments identify who your visitors are, what devices and services they
use, where they navigated from, and much more.
</Text>
</Content>
<Footer>
<Link>Learn more about segments</Link>
</Footer>
</ContextualHelp>
<ContextualHelp variant="help">
<Heading>What is a segment?</Heading>
<Content>
<Text>
Segments identify who your visitors are, what
devices and services they use, where they navigated
from, and much more.
</Text>
</Content>
<Footer>
<Link>Learn more about segments</Link>
</Footer>
</ContextualHelp>
<ContextualHelp variant="help">
<Heading>
What is a segment?
</Heading>
<Content>
<Text>
Segments identify
who your visitors
are, what devices
and services they
use, where they
navigated from,
and much more.
</Text>
</Content>
<Footer>
<Link>
Learn more about
segments
</Link>
</Footer>
</ContextualHelp>
Testing#
The ContextualHelpTrigger features an overlay that transitions in and out of the page as it is opened and closed. Please see the following sections in the testing docs for more information on how to handle these behaviors in your test suite.
Please also refer to React Spectrum's test suite if you find that the above isn't sufficient when resolving issues in your own test cases.