@atlaskit/spotlight
Version:
A spotlight introduces users to points of interest, from focused messages to multi-step tours.
84 lines (57 loc) • 3.37 kB
text/mdx
---
order: 0
---
import PlacementsExample from '../../examples/constellation/placements';
import SingleStepExample from '../../examples/constellation/single-step';
import MultipleStepsExample from '../../examples/constellation/multiple-steps';
import MediaExample from '../../examples/constellation/media';
import ControlsExample from '../../examples/constellation/controls';
import MotionExample from '../../examples/constellation/motion';
import ActionsAppearanceExample from '../../examples/constellation/actions-appearance';
import ActionsExample from '../../examples/constellation/actions';
## Single step
Always aim for a single step experience.
By design, `@atlaskit/spotlight` does not have a blanket, scroll-lock, or focus-trap functionality.
This is to ensure the user is not hijacked into the spotlight experience, and can opt-in if they are
interested.
To show/hide the `SpotlightCard`, simply use a `useState` to control the `isVisible` prop on
`PopoverContent`. To position the `SpotlightCard`, use `PopoverProvider`, `PopoverTarget` and
`PopoverContent` and set the `placement` prop.
<Example Component={SingleStepExample} packageName="@atlaskit/spotlight" />
## Multi-step tour
Multiple steps should be avoided if possible, but if they are required, manage the tour with a
`useState`. If `useState` is not feasible, then a React context may be used. However, these contexts
will often need to be wrapping the entire `App` and therefore will cause the entire `App` to
re-render every time a new spotlight step is shown.
<Example Component={MultipleStepsExample} packageName="@atlaskit/spotlight" />
## Placements
Spotlight placements are static. They do not change as the user scrolls, or if the `PopoverContent`
overflows out of the viewport. Make sure to choose a placement that ensures the `SpotlightCard` is
displayed in full.
<Example Component={PlacementsExample} packageName="@atlaskit/spotlight" />
## Media
Media is optional for a `SpotlightCard`and should only be used for more complex features. To ensure
correct reflow on smaller viewports, media must be 295px width X 135px height.
Media can be an image, gif, or video that helps communicate spotlight intent.
<Example Component={MediaExample} packageName="@atlaskit/spotlight" />
## Controls
`SpotlightDismissControl` is required for all `SpotlightCard` components. It **must** be the first
focusable element on the `SpotlightCard` card to provide an accessible experience.
## Actions
### Buttons
When the primary or secondary control should perform an in-app action (e.g. dismiss, advance to the
next step, or complete a flow), use `SpotlightPrimaryAction` and `SpotlightSecondaryAction`. They
accept an `onClick` handler and render as buttons.
`SpotlightPrimaryAction` and `SpotlightPrimaryLink` also accept an `appearance` prop, which allow
for brand styling.
<Example
Component={ActionsAppearanceExample}
packageName="@atlaskit/spotlight"
featureFlagSwitchers={['motion']}
/>
### Links
When the primary or secondary control should navigate to a URL instead of performing an action, use
`SpotlightPrimaryLink` and `SpotlightSecondaryLink`. They mirror the appearance of
`SpotlightPrimaryAction` and `SpotlightSecondaryAction` but render as links (e.g. "Get started",
"Learn more").
<Example Component={ActionsExample} packageName="@atlaskit/spotlight" />