@atlaskit/spotlight/constellation/index/examples.mdx

A spotlight introduces users to points of interest, from focused messages to multi-step tours.

---
order: 0
---

import SectionMessage from '@atlaskit/section-message';
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';

<SectionMessage title="Motion in Early Access" appearance="warning">
	The motion added into Spotlight is in Early Access. The motion updates are currently behind the
	feature flag: platform-dst-motion-uplift-spotlight.
</SectionMessage>

## 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"
	featureFlagSwitchers={['motionSpotlight']}
/>

## 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"
	featureFlagSwitchers={['motionSpotlight']}
/>

## 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"
	featureFlagSwitchers={['motionSpotlight']}
/>

## 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"
	featureFlagSwitchers={['motionSpotlight']}
/>

## 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"
	featureFlagSwitchers={['motionSpotlight']}
/>