## Component Name
SpotlightPopoverTour
## Description
The SpotlightPopoverTour component is used to provide context as well as enable users to take certain actions on it. These are used to highlight a new feature or provide a guided tour to a new user. The component can spotlight specific UI elements on the page and present a series of steps with descriptions.
## TypeScript Types
Below are the TypeScript types that define the props that the SpotlightPopoverTour and its subcomponents accept:
```typescript
// Main component props
type SpotlightPopoverTourProps = {
/**
* Array of steps to be rendered
*
* The order of the steps will be the order in which they are rendered depending on the `activeStep` prop
*/
steps: SpotlightPopoverTourSteps;
/**
* Whether the tour is visible or not
*/
isOpen: boolean;
/**
* Callback when the tour is opened or closed
*/
onOpenChange?: ({ isOpen }: { isOpen: boolean }) => void;
/**
* Callback which fires when the `stopTour` method is called from the `steps` array
*/
onFinish?: () => void;
/**
* Callback when the active step changes
*/
onStepChange?: (step: number) => void;
/**
* Active step to be rendered
*/
activeStep: number;
children: React.ReactNode;
};
// Tour step props
type SpotlightPopoverTourStepProps = {
name: string;
children: React.ReactNode;
};
// Tour step definition
type Step = {
/**
* Unique identifier for the tour step
*/
name: string;
/**
* Content of the Popover
*/
content: (props: SpotlightPopoverStepRenderProps) => React.ReactElement;
/**
* Footer content
*/
footer?: (props: SpotlightPopoverStepRenderProps) => React.ReactNode;
/**
* Popover title
*/
title?: string;
/**
* Leading content placed before the title
*
* Can be any blade icon or asset.
*/
titleLeading?: React.ReactNode;
/**
* Placement of Popover
* @default "top"
*/
placement?: UseFloatingOptions['placement'];
};
// Array of Step objects
type SpotlightPopoverTourSteps = Step[];
// Props passed to render functions
type SpotlightPopoverStepRenderProps = {
/**
* Go to a specific step
*/
goToStep: (step: number) => void;
/**
* Go to the next step
*/
goToNext: () => void;
/**
* Go to the previous step
*/
goToPrevious: () => void;
/**
* Stop the tour
*
* This will call the `onFinish` callback
*/
stopTour: () => void;
/**
* Current active step (zero based index)
*/
activeStep: number;
/**
* Total number of steps
*/
totalSteps: number;
};
```
## Example
### Basic Tour Example
This example demonstrates a simple guided tour with three steps highlighting different UI elements, using a custom footer component to control navigation between steps.
```tsx
import { useState } from 'react';
import {
SpotlightPopoverTour,
SpotlightPopoverTourStep,
SpotlightPopoverTourFooter,
Box,
Button,
Text,
Card,
CardBody,
InfoIcon,
Amount,
} from '@razorpay/blade/components';
import type {
SpotlightPopoverTourSteps,
SpotlightPopoverStepRenderProps,
} from '@razorpay/blade/components';
// Custom footer component that can control the tour
const CustomTourFooter = ({
activeStep,
totalSteps,
goToNext,
goToPrevious,
stopTour,
}: SpotlightPopoverStepRenderProps): React.ReactElement => {
const isLast = activeStep === totalSteps - 1;
const isFirst = activeStep === 0;
return (
);
};
function BasicTourExample(): React.ReactElement {
const [activeStep, setActiveStep] = useState(0);
const [isOpen, setIsOpen] = useState(false);
// Define the tour steps
const steps: SpotlightPopoverTourSteps = [
{
name: 'refunds-step',
title: 'Overview of Refunds',
content: () => (
You can issue refunds for various reasons, like when a customer returns a product or
cancels a service.
You can also issue partial refunds - for example, if a customer purchased multiple
items.
),
placement: 'bottom' as const,
footer: CustomTourFooter,
},
{
name: 'disputes-step',
title: 'Overview of Disputes',
content: () => (
Disputes are raised by customers when they have a problem with a transaction.
),
placement: 'bottom' as const,
footer: CustomTourFooter,
},
{
name: 'status-step',
title: 'Dispute Statuses',
content: () => (
Disputes which are open or under review will be shown here. You can also review them by
clicking on the button.
),
placement: 'bottom' as const,
footer: CustomTourFooter,
},
];
return (
{
setActiveStep(0);
setIsOpen(false);
}}
onOpenChange={({ isOpen }) => {
setIsOpen(isOpen);
}}
onStepChange={(step) => {
setActiveStep(step);
}}
>
Refunds3 ProcessedDisputes0 Open | 0 Under review
);
}
export default BasicTourExample;
```
### Interruptible Tour Example
This example shows an advanced implementation of a tour that can be interrupted or skipped, with dynamic step content that changes based on whether the user completed or skipped the tour.
```tsx
import { useState } from 'react';
import {
SpotlightPopoverTour,
SpotlightPopoverTourStep,
Box,
Button,
Text,
Code,
} from '@razorpay/blade/components';
import type {
SpotlightPopoverTourSteps,
SpotlightPopoverStepRenderProps,
} from '@razorpay/blade/components';
const InterruptibleTourFooter = ({
activeStep,
goToNext,
goToStep,
stopTour,
goToPrevious,
totalSteps,
setIsTourSkipped,
}: SpotlightPopoverStepRenderProps & {
setIsTourSkipped: (isTourSkipped: boolean) => void;
}): React.ReactElement => {
const isLast = activeStep === totalSteps - 1;
const isFirst = activeStep === 0;
return (
{activeStep + 1} / {totalSteps}
{!isFirst && (
)}
{isLast ? (
) : (
)}
);
};
function InterruptibleTourExample(): React.ReactElement {
const [activeStep, setActiveStep] = useState(0);
const [isTourSkipped, setIsTourSkipped] = useState(false);
const [isOpen, setIsOpen] = useState(false);
// Define steps dynamically based on state
const steps: SpotlightPopoverTourSteps = [
{
name: 'step-1',
title: 'Step 1',
content: () => (
This is step 1, press skip
),
placement: 'top' as const,
footer: (props) => (
),
},
{
name: 'step-2',
title: 'Step 2',
content: () => (
This is step 2
),
placement: 'bottom' as const,
footer: (props) => (
),
},
// The final step changes based on whether user skipped or completed
isTourSkipped
? {
name: 'final-step',
title: 'Tour Incomplete!',
content: () => (
We recommend that you complete the tour to make the most of the new features. You can
find it here when you want to take it.
),
footer: ({ stopTour }) => (
),
}
: {
name: 'final-step',
title: 'Tour Complete!',
content: () => (
You have completed the tour. You can find it here when you want to take it.
),
footer: ({ stopTour }) => (
),
},
];
return (
{
setIsOpen(false);
setIsTourSkipped(false);
setActiveStep(0);
}}
onOpenChange={({ isOpen }) => {
setIsOpen(isOpen);
}}
onStepChange={(step) => {
setActiveStep(step);
}}
>
You can create complex flows like interruptible tours by dynamically modifying the steps
array, and changing its contents.
Compose and make use of methods provided by the tour component like{' '}
stopTour, goToStep,{' '}
goToNext etc to control the behavior of the current tour step
Step 1
Step 2
);
}
export default InterruptibleTourExample;
```