React Native Spotlight Tour

https://stackbuilders.github.io/react-native-spotlight-tour/docs
Admin
React Native Spotlight Tour is a library for creating interactive guided tours and spotlight...
Tokens:4,238
Snippets:32
Trust Score:9.7
Update:6 months ago
Show doc for...
Tokens:
Raw
### SpotlightTour Context Methods

Source: https://stackbuilders.github.io/react-native-spotlight-tour/docs/build/interfaces/SpotlightTour.html

Methods for controlling the lifecycle and navigation of the spotlight tour.

```APIDOC
## SpotlightTour Methods

### Description
Methods to navigate, start, stop, pause, and resume the spotlight tour.

### Methods
- **goTo(index: number)**: Moves to a specific step index.
- **next()**: Advances to the next step.
- **previous()**: Returns to the previous step.
- **start()**: Initiates the tour from the first step.
- **stop()**: Terminates the tour.
- **pause()**: Pauses the tour execution.
- **resume()**: Resumes the tour execution.

### Properties
- **current** (number) - Optional - The current step index.
- **status** (TourStatus) - The current status of the tour.

### Usage Example
```javascript
const { start, next, stop } = useSpotlightTour();

// Start the tour
start();

// Move to next step
next();

// Stop the tour
stop();
```
```

--------------------------------

### SpotlightTourProviderProps Configuration

Source: https://stackbuilders.github.io/react-native-spotlight-tour/docs/build/interfaces/SpotlightTourProviderProps.html

Configuration object for the SpotlightTourProvider, accepting Floating UI middleware, placement, and sameScrollView configurations. It also extends TooltipProps.

```APIDOC
## SpotlightTourProviderProps

### Description
Configuration object which accepts Floating Ui middleware, placement and sameScrollView configurations.

### Extends
* `TooltipProps`

### Properties

#### arrow? (number | boolean | ArrowOptions)
Tooltip arrow options. It accepts 3 types of value:
* boolean: When `false`, disable rendering the arrow. While `true` renders using the default values.
* number: Use it to change the size of the arrow only.
* object: Options to further customize the arrow style.

**Default:** `20`

**Inherited from:** `TooltipProps`.`arrow`

#### children (ReactNode | ChildFn<SpotlightTour>)
The children to render in the provider. It accepts either a React component, or a function that returns a React component. When the child is a function, the `SpotlightTour` context can be accessed from the first argument.

#### flip? (boolean | FlipOptions)
Enables flipping the placement of the tooltip in order to keep it in view.

**Default:** `true`

**Inherited from:** `TooltipProps`.`flip`

#### motion? (Motion)
Sets the default transition motion for all steps. You can override this value on each step too.

**Default:** `bounce`

#### nativeDriver? (boolean | OSConfig<boolean>)
Define if the animations in the tour should use the native driver or not. A boolean can be used to apply the same value to both Android and iOS, or an object with `android` and `ios` keys can be used to define a value for each OS.

**Default:** `false`

#### offset? (number)
Offset points between the tooltip and the spotlight.

**Default:** `4`

**Inherited from:** `TooltipProps`.`offset`

#### onBackdropPress? (BackdropPressBehavior)
Sets the default behavior of pressing the tour’s backdrop. You can use either one of the following values:
* A callback function with the SpotlightTour options object in the first argument. This allows more granular control over the tour.
* The `continue` literal string, which is a shortcut to move to the next step, and stop the tour on the last step.
* the `stop` literal string, which is a shortcut to stop the tour.

**NOTE:** You can also override this behavior on each step configuration.

#### onPause? ((values) => void)
Handler which gets executed when pause is invoked. It receives the TourState so you can access the step index where the tour paused.

**Parameters:**
* **values** (`TourState`)

**Returns:** `void`

#### onResume? ((values) => void)
Handler which gets executed when resume is invoked. It receives the ResumeParams so you can access the step index where the tour resumed.

**Parameters:**
* **values** (`TourState`)

**Returns:** `void`

#### onStop? ((values) => void)
Handler which gets executed when stop is invoked. It receives the TourState so you can access the `current` step index where the tour stopped and a bool value `isLast` indicating if the step where the tour stopped is the last one.

**Parameters:**
* **values** (`TourState`)

**Returns:** `void`

#### overlayColor? (ColorValue)
The color of the overlay of the tour.

**Default:** `black`

#### overlayOpacity? (number)
The opacity applied to the overlay of the tour (between 0 to 1).

**Default:** `0.45`
```

--------------------------------

### ShapeOptions Interface

Source: https://stackbuilders.github.io/react-native-spotlight-tour/docs/build/interfaces/ShapeOptions.html

Details the properties available for configuring the shape of the spotlight, including padding and type.

```APIDOC
## Interface: ShapeOptions

### Description
Configuration options for the shape of the spotlight.

### Properties

#### padding
- **padding** (number) - Optional - The padding around the spotlight shape. A value of 0 means the shape fits exactly around the component. Measured in points.
  - Default: `16`

#### type
- **type** (Shape) - Optional - The shape of the spotlight. Possible values are `circle` or `rectangle`.
  - Default: `circle`
```

--------------------------------

### AttachStepProps Interface

Source: https://stackbuilders.github.io/react-native-spotlight-tour/docs/build/interfaces/AttachStepProps.html

Details the properties available for the AttachStep component, used to define individual steps in a spotlight tour.

```APIDOC
## AttachStepProps

### Description
Defines the properties for an individual step within a React Native Spotlight Tour. This component is used to attach spotlights to specific elements in the UI.

### Properties

#### children
- **children** (ReactElement<ChildProps>) - Required - The React element that the spotlight will be wrapped around for this step of the tour.

#### fill
- **fill** (boolean) - Optional - Determines if the spotlight wrapper should stretch to fill its parent view. Defaults to `false`. This prop has no effect on native components or components using `React.forwardRef`.

#### index
- **index** (number | number[]) - Required - The index or an array of indices in the `steps` array to which this step is attached.

#### style
- **style** (StyleProp<ViewStyle>) - Optional - Custom styling to be applied to the AttachStep wrapper.
```

--------------------------------

### SpotlightTour Component Props

Source: https://stackbuilders.github.io/react-native-spotlight-tour/docs/build/interfaces/SpotlightTourProviderProps.html

This section details the configurable props for the SpotlightTour component, including placement, shape, shift, and steps.

```APIDOC
## SpotlightTour Component Props

### Description

This section details the configurable props for the SpotlightTour component, including placement, shape, shift, and steps.

### Parameters

#### Props

- **placement** (Placement) - Optional - The placement of the tooltip relative to the spotlight. Defaults to "bottom". Inherited from `TooltipProps`.
- **shape** (Shape | ShapeOptions) - Optional - Configures the default spotlight shape for all steps. This can be overridden on each step. Defaults to `circle`.
- **shift** (boolean | ShiftOptions) - Optional - Enables shifting the tooltip in order to keep it in view. Defaults to `{ padding: 8 }`. Inherited from `TooltipProps`.
- **steps** (TourStep[]) - Required - An array of `TourStep` objects that define each step of the tour.
```

--------------------------------

### autoPlacement()

Source: https://stackbuilders.github.io/react-native-spotlight-tour/docs/build/variables/autoPlacement.html

Optimizes the visibility of the floating element by automatically choosing the placement with the most available space. This serves as an alternative to the 'flip' middleware.

```APIDOC
## autoPlacement()

### Description
Optimizes the visibility of the floating element by choosing the placement that has the most space available automatically, without needing to specify a preferred placement. Alternative to `flip`.

### Method
`const`

### Endpoint
`autoPlacement(options?, deps?)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```json
{
  "example": "autoPlacement({ alignment: 'center' }, [dependency])"
}
```

### Response
#### Success Response (200)
- **Middleware** (object) - Returns the middleware function for auto placement.

#### Response Example
```json
{
  "example": "// Returns a Middleware object"
}
```

### See
https://floating-ui.com/docs/autoPlacement
```

--------------------------------

### Middleware: shift()

Source: https://stackbuilders.github.io/react-native-spotlight-tour/docs/build/variables/shift.html

Documentation for the shift middleware function used to keep floating elements within view.

```APIDOC
## [FUNCTION] shift()

### Description
Optimizes the visibility of the floating element by shifting it in order to keep it in view when it will overflow the clipping boundary.

### Method
N/A (Middleware Function)

### Endpoint
shift(options?, deps?)

### Parameters
#### Arguments
- **options** (ShiftOptions | Derivable<ShiftOptions>) - Optional - Configuration options for the shift behavior.
- **deps** (React.DependencyList) - Optional - React dependency list to trigger re-calculation.

### Returns
- **Middleware** - Returns a middleware object for the floating UI configuration.

### Usage Example
```javascript
import { shift } from '@floating-ui/react-native';

const middleware = [shift({ padding: 5 })];
```

### See
https://floating-ui.com/docs/shift
```

--------------------------------

### Middleware: inline()

Source: https://stackbuilders.github.io/react-native-spotlight-tour/docs/build/variables/inline.html

Provides improved positioning for inline reference elements that can span over multiple lines, such as hyperlinks or range selections.

```APIDOC
## [FUNCTION] inline()

### Description
Provides improved positioning for inline reference elements that can span over multiple lines, such as hyperlinks or range selections.

### Method
N/A (Middleware Function)

### Parameters
#### Options
- **options** (InlineOptions | Derivable<InlineOptions>) - Optional - Configuration options for the inline middleware.

#### Dependencies
- **deps** (React.DependencyList) - Optional - React dependency list to trigger re-computation.

### Returns
- **Middleware** - Returns a middleware object for use with the floating-ui configuration.

### Usage Example
```javascript
import { inline } from '@floating-ui/react-native';

const middleware = [inline()];
```

### See Also
https://floating-ui.com/docs/inline
```

--------------------------------

### TourBox Component Constructor (React Native)

Source: https://stackbuilders.github.io/react-native-spotlight-tour/docs/build/functions/TourBox.html

The TourBox component is a built-in tooltip container for each step in the spotlight tour. It is highly customizable but not mandatory, allowing for replacement with custom components. It accepts props of type TourBoxProps and returns a ReactElement.

```typescript
function TourBox(props: TourBoxProps): ReactElement
```

--------------------------------

### Interface: ChildProps

Source: https://stackbuilders.github.io/react-native-spotlight-tour/docs/build/interfaces/ChildProps.html

Defines the properties for the AttachStep component, allowing for layout tracking and reference management.

```APIDOC
## Interface: ChildProps

### Description
The ChildProps interface defines the props accepted by the AttachStep component in the React Native Spotlight Tour library.

### Properties

- **children** (ReactNode) - Optional - A React children element, if any.

- **onLayout** (Function) - Optional - Callback function triggered on native component layout change.
  - **Parameters**:
    - **event** (LayoutChangeEvent) - The layout event object.
  - **Returns**: void

- **ref** (RefObject<unknown>) - Required - A React reference object for the component.

### Usage Example
```tsx
<AttachStep ref={myRef} onLayout={(event) => console.log(event)}>
  <View />
</AttachStep>
```
```

--------------------------------

### Offset Middleware Configuration in React Native

Source: https://stackbuilders.github.io/react-native-spotlight-tour/docs/build/variables/offset.html

The offset middleware modifies the placement of a floating element by translating it along specified axes. It accepts optional options for configuration and dependencies. This middleware is crucial for fine-tuning the positioning of tooltips or spotlights in React Native applications.

```typescript
const offset = (options?: OffsetOptions, deps?: React.DependencyList): Middleware;
```

--------------------------------

### Type Alias: BackdropPressBehavior

Source: https://stackbuilders.github.io/react-native-spotlight-tour/docs/build/type-aliases/BackdropPressBehavior.html

Documentation for the BackdropPressBehavior type alias, which controls how the tour reacts to backdrop interactions.

```APIDOC
## BackdropPressBehavior

### Description
Defines the behavior of the backdrop when pressed during a spotlight tour. It can either trigger a predefined action or execute a custom callback function.

### Type Definition
`BackdropPressBehavior` = `"continue"` | `"stop"` | (`options`) => `void`

### Options
- **"continue"**: Advances the tour to the next step.
- **"stop"**: Terminates the current tour.
- **(options) => void**: A custom callback function that receives tour options to handle the press event manually.

### Location
`package/src/lib/SpotlightTour.context.ts:104`
```

--------------------------------

### Configure TourStep Shift Behavior

Source: https://stackbuilders.github.io/react-native-spotlight-tour/docs/build/interfaces/TourStep.html

Enables shifting the tooltip to maintain visibility. The default configuration includes a padding of 8 pixels.

```typescript
const shift = { padding: 8 };
```

--------------------------------

### Configure TourStep Arrow Options

Source: https://stackbuilders.github.io/react-native-spotlight-tour/docs/build/interfaces/TourStep.html

Defines the arrow configuration for a tour step. It accepts a boolean to toggle visibility, a number for size, or an object for detailed styling.

```typescript
const arrowConfig = 20;
```

--------------------------------

### SpotlightTourProvider Component Definition

Source: https://stackbuilders.github.io/react-native-spotlight-tour/docs/build/variables/SpotlightTourProvider.html

Defines the SpotlightTourProvider, a React provider component used to access the SpotlightTour context. It's a forward-ref exotic component that accepts SpotlightTourProviderProps and returns a SpotlightTour ref.

```typescript
const SpotlightTourProvider : ForwardRefExoticComponent<SpotlightTourProviderProps & RefAttributes<SpotlightTour>>
```

--------------------------------

### TourStatus Type Alias

Source: https://stackbuilders.github.io/react-native-spotlight-tour/docs/build/type-aliases/TourStatus.html

Defines the possible states for the tour's status.

```APIDOC
## TourStatus Type Alias

### Description
Defines the possible states for the tour's status.

### Type Alias
`TourStatus`

### Possible Values
- `"idle"
- `"running"
- `"paused"

### Defined In
`package/src/lib/SpotlightTour.context.ts:12`
```

--------------------------------

### Optional Type Alias

Source: https://stackbuilders.github.io/react-native-spotlight-tour/docs/build/type-aliases/Optional.html

Documentation for the Optional type alias, which makes a type optional by allowing it to be undefined.

```APIDOC
## Type Alias: Optional<T>

### Description
Makes the target optional. I.e, it can be the target type or `undefined`.

### Type Parameters
#### T
`T`
```

--------------------------------

### Define TourStep Flip Behavior

Source: https://stackbuilders.github.io/react-native-spotlight-tour/docs/build/interfaces/TourStep.html

Configures the flip middleware for the tooltip to ensure it remains visible within the viewport. Defaults to true.

```typescript
const flip = true;
```

--------------------------------

### Define BackdropPressBehavior type alias

Source: https://stackbuilders.github.io/react-native-spotlight-tour/docs/build/type-aliases/BackdropPressBehavior.html

The BackdropPressBehavior type defines how the tour responds to backdrop presses. It accepts either a string literal ('continue' or 'stop') or a callback function that receives options and returns void.

```typescript
type BackdropPressBehavior = "continue" | "stop" | (options: any) => void;
```

--------------------------------

### OSConfig Interface Definition (TypeScript)

Source: https://stackbuilders.github.io/react-native-spotlight-tour/docs/build/interfaces/OSConfig.html

Defines the OSConfig interface with generic type parameter T. It includes properties for Android, iOS, and Web, allowing for platform-specific configurations.

```typescript
interface OSConfig<T> {
  android?: T;
  ios?: T;
  web?: T;
}
```

--------------------------------

### Arrow Middleware

Source: https://stackbuilders.github.io/react-native-spotlight-tour/docs/build/variables/arrow.html

The `arrow` middleware is used to position an inner element of a floating element, centering it relative to the reference element. It wraps the core `arrow` middleware from Floating UI to support React refs.

```APIDOC
## `arrow()`

### Description
Provides data to position an inner element of the floating element so that it appears centered to the reference element. This wraps the core `arrow` middleware to allow React refs as the element.

### Method
`const arrow = (options, deps?) => Middleware`

### Parameters
#### Options
- **options** (`ArrowOptions` | `Derivable<ArrowOptions>`) - Required - Configuration options for the arrow middleware.

#### Dependencies
- **deps?** (`React.DependencyList`) - Optional - A list of dependencies for the middleware.

### Returns
- **Middleware** - The configured arrow middleware.

### See
- https://floating-ui.com/docs/arrow
```

--------------------------------

### hide() Function API

Source: https://stackbuilders.github.io/react-native-spotlight-tour/docs/build/variables/hide.html

The hide() function is a middleware that provides data to hide the floating element in certain scenarios, such as when it's not within the same clipping context as the reference element.

```APIDOC
## hide() API

### Description
Provides data to hide the floating element in applicable situations, such as when it is not in the same clipping context as the reference element.

### Method
`const`

### Endpoint
N/A (This is a function, not an HTTP endpoint)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```javascript
import { hide } from '@floating-ui/react-native';

// Example usage within a component or setup
const middleware = [
  hide(),
  // other middleware...
];
```

### Response
#### Success Response
Returns `Middleware` which is used in floating-ui configurations.

#### Response Example
```json
{
  "name": "hide",
  "options": {},
  "data": {
    "referenceHidden": true // Example data structure
  }
}
```

### See Also
- [https://floating-ui.com/docs/hide](https://floating-ui.com/docs/hide)
```

--------------------------------

### Set TourStep Placement

Source: https://stackbuilders.github.io/react-native-spotlight-tour/docs/build/interfaces/TourStep.html

Determines the relative position of the tooltip to the spotlighted element. Defaults to 'bottom'.

```typescript
const placement = "bottom";
```

--------------------------------

### Motion Type Alias Definition

Source: https://stackbuilders.github.io/react-native-spotlight-tour/docs/build/type-aliases/Motion.html

Defines the possible string values for the 'Motion' type alias used in React Native Spotlight Tour. This type specifies the visual effect applied to the spotlight during tour transitions.

```typescript
export type Motion = "bounce" | "fade" | "slide";
```

--------------------------------

### Type Alias: Shape

Source: https://stackbuilders.github.io/react-native-spotlight-tour/docs/build/type-aliases/Shape.html

Defines the valid shape configurations for the spotlight tour component.

```APIDOC
## Type Alias: Shape

### Description
Defines the possible geometric shapes that can be applied to the spotlight tour component.

### Definition
`Shape` = `"circle"` | `"rectangle"`

### Values
- **circle**: Renders the spotlight as a circular mask.
- **rectangle**: Renders the spotlight as a rectangular mask.

### Usage
This type is used within the `SpotlightTour.context.ts` to determine the visual rendering of the spotlight overlay.
```

--------------------------------

### AttachStep Component Definition (TypeScript)

Source: https://stackbuilders.github.io/react-native-spotlight-tour/docs/build/functions/AttachStep.html

Defines the AttachStep React functional component. It accepts props of type AttachStepProps to customize its behavior for attaching and stepping to other components. The component returns a ReactElement.

```typescript
function AttachStep(props: AttachStepProps): ReactElement {
  // Component implementation
}
```

--------------------------------

### Define Shape Type Alias (TypeScript)

Source: https://stackbuilders.github.io/react-native-spotlight-tour/docs/build/type-aliases/Shape.html

This TypeScript code defines the 'Shape' type alias, which specifies the possible shapes for the tour spotlight. It accepts either 'circle' or 'rectangle' as valid string literals. This type is used to ensure type safety when configuring the spotlight's appearance.

```typescript
export type Shape = "circle" | "rectangle";
```

--------------------------------

### Define ChildFn Type Alias

Source: https://stackbuilders.github.io/react-native-spotlight-tour/docs/build/type-aliases/ChildFn.html

The ChildFn type alias defines a function signature that takes a generic value and returns a ReactNode. It is used to standardize how child components are rendered when passed as functions within the library.

```typescript
type ChildFn<T> = (value: T) => ReactNode;
```

--------------------------------

### Type Alias: ToOptional<T> in TypeScript

Source: https://stackbuilders.github.io/react-native-spotlight-tour/docs/build/type-aliases/ToOptional.html

The `ToOptional<T>` type alias transforms the value types of an object to be `Optional`. It iterates over the keys of the required properties of `T` and maps them to `Optional<T[K]>`. This is defined in `package/src/helpers/common.ts`.

```typescript
type ToOptional<T> = { [K in keyof Required<T>]: Optional<T[K]> };
```

--------------------------------

### Define OmitR Type Alias

Source: https://stackbuilders.github.io/react-native-spotlight-tour/docs/build/type-aliases/OmitR.html

The OmitR type alias is a utility that constructs a type by picking all properties from T except those in K. It specifically constrains T to be a Record type, ensuring type safety when omitting keys from object structures.

```typescript
type OmitR<T extends Record<keyof unknown, unknown>, K extends keyof T> = Pick<T, Exclude<keyof T, K>>;
```
Tokens:
Raw