React Instastories

https://react-instastories.js.org/docs
Admin
React Instastories is a library that simplifies embedding user and system stories into web...
Tokens:12,350
Snippets:148
Trust Score:8.1
Update:2 months ago
Show doc for...
Tokens:
Raw
### Installing preset packages

Source: https://react-instastories.js.org/docs/presets/how-to-use

Install the base and presets packages via npm.

```bash
npm install @react-instastories/base @react-instastories/presets
```

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

### Install react-instastories libraries via NPM

Source: https://react-instastories.js.org/docs/install

Use this command to install the base, external, and presets packages for react-instastories.

```bash
npm install @react-instastories/base @react-instastories/external @react-instastories/presets
```

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

### Implementing ARIA Toolbar Support

Source: https://react-instastories.js.org/docs/base/preview

Example of integrating the Preview component within a toolbar using @react-aria/toolbar for accessibility.

```jsx
import { useToolbar } from "@react-aria/toolbar";
import React from "react";
 
export function AppStories() {
  const ref = React.useRef(null);
  const { toolbarProps } = useToolbar({ "aria-label": "Stories" }, ref);
 
  return (
    <InstaStories>
      <Stories {...toolbarProps} ref={ref}>
        <Story>
          <Preview>Preview Content #1</Preview>
          {...pages}
        </Story>
        <Story>
          <Preview>Preview Content #2</Preview>
          {...pages}
        </Story>
        <Story>
          <Preview>Preview Content #3</Preview>
          {...pages}
        </Story>
      </Stories>
    </InstaStories>
  );
}
```

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

### Implement Story component

Source: https://react-instastories.js.org/docs/base/story

Basic implementation of the Story component with custom duration, starting page, and event handlers.

```jsx
<Story
  preload
  duration={20000}
  start={1}
  onOpen={() => console.debug("Story opened!")}
  onClose={() => console.debug("Story closed!")}
>
  <Pages>
    <Page>Page with index #0</Page>
    <Page>Page with index #1</Page>
    <Page>Page with index #2</Page>
  </Pages>
</Story>
```

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

### InstaStories component usage

Source: https://react-instastories.js.org/docs/presets/how-to-use

Examples of using the InstaStories component with default styles, custom class names, or specific presets.

```jsx
// uses default styles imported just above
<InstaStories>{...stories}</InstaStories>
```

```jsx
// uses default styles imported just above
<InstaStories
  config={{
    viewer: { props: { className: "any-class-name-viewer" } },
    preview: { props: { className: "any-class-name-preview" } }
  }}
>
  {...stories}
</InstaStories>
```

```jsx
// disables the use of styles imported just above
<InstaStories config={{ preset: "instastories-preset-name" }}>
  {...stories}
</InstaStories>
```

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

### Basic Usage of Configurable Components

Source: https://react-instastories.js.org/docs/base/configurable

Demonstrates the hierarchical structure for wrapping viewer, story, and page configurations within a container.

```jsx
<Configurable.Container>
  <Configurable.Viewer events={events}>{...components}</Configurable.Viewer>
  <Configurable.Story events={events}>{...components}</Configurable.Story>
  <Configurable.Page events={events}>{...components}</Configurable.Page>
</Configurable.Container>
```

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

### Implementing useKeyboardMovement

Source: https://react-instastories.js.org/docs/external/hooks/keyboard-movement

Initialize the hook by passing the stories context object to enable keyboard navigation.

```javascript
const stories = useStoriesContext();
 
useKeyboardMovement(stories);
```

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

### Create presets from scratch

Source: https://react-instastories.js.org/docs/presets/how-to-create

Define a custom preset using data attributes and apply it to the InstaStories component.

```css
[data-preset="instastories-preset-example"].instastories-viewer,
[data-preset="instastories-preset-example"].instastories-stories, {
  --is-preset-name: "example";
}
 
[data-preset="instastories-preset-example"].instastories-viewer--entering,
[data-preset="instastories-preset-example"].instastories-viewer--entered {
  background-color: #39f6;
}
 
/* ... any other CSS stylesheet ... */
```

```javascript
import "path/to/file/example.css";
 
<InstaStories config={{ preset: "instastories-preset-example" }}>
  {...content}
</InstaStories>;
```

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

### Basic Preview Usage

Source: https://react-instastories.js.org/docs/base/preview

Standard implementation of the Preview component with event handlers for click, show, and hide actions.

```jsx
<Preview
  onClick={() => console.debug("Preview clicked!")}
  onShow={() => console.debug("Preview is shown!")}
  onHide={() => console.debug("Preview is hidden!")}
>
  <h1>Preview Content</h1>
</Preview>
```

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

### Importing default stylesheets

Source: https://react-instastories.js.org/docs/presets/how-to-use

Import the base and external component stylesheets to enable default styling.

```javascript
// default stylesheet for base components
import "@react-instastories/base/index.css";
// default stylesheet for external components
import "@react-instastories/external/index.css";
```

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

### Implement Preloadable Stories and Pages

Source: https://react-instastories.js.org/docs/external/preloadable

Configures Preloadable components within a Configurable container to manage content preloading behavior.

```javascript
import { Configurable } from "@react-instastories/base";
import { Preloadable } from "@react-instastories/external";
 
function AppStories() {
  return (
    <Configurable.Container>
      <Configurable.Viewer>
        <Preloadable.Stories unloadable next={1} previous={1} />
        <Preloadable.Pages unloadable next={1} previous={1} />
      </Configurable.Viewer>
    </Configurable.Container>
  );
}
```

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

### Basic Indicator Implementation

Source: https://react-instastories.js.org/docs/external/controls/indicator

Integrate the Indicator component within a Configurable container to manage story progress.

```javascript
import { Configurable } from "@react-instastories/base";
import { Controls } from "@react-instastories/external";
 
function AppStories() {
  return (
    <Configurable.Container>
      <Configurable.Story>
        <Controls.Indicator interactive threshold={1000} />
      </Configurable.Story>
    </Configurable.Container>
  );
}
```

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

### Applying a custom preset

Source: https://react-instastories.js.org/docs/presets/how-to-use

Import a specific preset CSS file and configure the InstaStories component to use it via the preset name.

```jsx
import {
  InstaStories,
  Page,
  Pages,
  Preview,
  Stories,
  Story
} from "@react-instastories/base";
 
// ... or another stylesheet preset that contains [data-preset="{name}"] selector ...
import "@react-instastories/presets/tg.css";
 
function AppStories() {
  return (
    <InstaStories
      config={{
        preset: "instastories-preset-tg" // ... the name of the preset contained in the CSS file above ...
      }}
    >
      <Stories>
        <Story>
          <Preview>Preview Content</Preview>
          <Pages>
            <Page>Page Content</Page>
          </Pages>
        </Story>
      </Stories>
    </InstaStories>
  );
}
```

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

### Implement InstaStories Component

Source: https://react-instastories.js.org/docs/base/instastories

Basic implementation of the InstaStories component structure including Stories, Story, Preview, and Pages.

```javascript
import {
  InstaStories,
  Page,
  Pages,
  Preview,
  Stories,
  Story
} from "@react-instastories/base";
 
import "@react-instastories/base/index.css";
 
export function AppStories() {
  return (
    <InstaStories>
      <Stories>
        <Story>
          <Preview>Preview Content</Preview>
          <Pages>
            <Page>Page Content</Page>
          </Pages>
        </Story>
      </Stories>
    </InstaStories>
  );
}
```

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

### Configuring Viewer Events and Controls

Source: https://react-instastories.js.org/docs/base/configurable

Configures the viewer with specific event handlers and UI controls for navigation and preloading.

```jsx
<Configurable.Container>
  <Configurable.Viewer
    events={[
      Events.Mount.AutoClose,
      Events.Mount.Interactive,
      Events.Focus.Timer,
      Events.Keyboard.Close,
      Events.Keyboard.Stories
    ]}
  >
    <Controls.Viewer.Background />
    <Controls.Viewer.Close />
    <Controls.Stories.Next />
    <Controls.Stories.Previous />
    <Preloadable.Stories unloadable next={1} previous={1} />
    <Preloadable.Pages unloadable next={1} previous={1} />
  </Configurable.Viewer>
</Configurable.Container>
```

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

### Configure Linear Animation

Source: https://react-instastories.js.org/docs/base/models/animation

Uses pure CSS for step-by-step animations without tracking the preview component. Provides a more performance-friendly alternative to smart animation.

```jsx
<InstaStories config={{ animation: "linear" }}>
  {...configurable}
  {...stories}
</InstaStories>
```

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

### Implement Custom Pagination with usePagination

Source: https://react-instastories.js.org/docs/base/hooks/pagination

Demonstrates how to integrate the usePagination hook to manage navigation between children elements with custom buttons and state display.

```typescript
import { usePagination } from "@react-instastories/base";
 
import React from "react";
 
function CustomPaginationComponent({ children }) {
  const { canNext, canPrevious, current, length, change } =
    usePagination(children);
 
  return (
    <div>
      <button onClick={() => change(current - 1)} disabled={!canPrevious}>
        Previous
      </button>
      <div>{React.Children.toArray(children)[current]}</div>
      <button onClick={() => change(current + 1)} disabled={!canNext}>
        Next
      </button>
      <p>
        Current {current + 1} of {length}
      </p>
    </div>
  );
}
```

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

### Accessing Configuration with useConfig

Source: https://react-instastories.js.org/docs/base/hooks/config

Import and call the hook within a component to retrieve the current configuration object.

```javascript
import { useConfig } from "@react-instastories/base";
 
import React from "react";
 
function DebugConfig() {
  const config = useConfig();
 
  React.useEffect(() => console.debug(config), [config]);
 
  return <pre>{JSON.stringify(config, null, 2)}</pre>;
}
```

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

### Configure Smart Animation

Source: https://react-instastories.js.org/docs/base/models/animation

Enables a CSS-in-JS pulse animation that tracks the preview component's bounding box. Avoid on older devices due to potential performance overhead.

```jsx
<InstaStories config={{ animation: "smart" }}>
  {...configurable}
  {...stories}
</InstaStories>
```

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

### Accessing Viewer Transition State

Source: https://react-instastories.js.org/docs/base/models/transition

Use the useViewerContext hook to retrieve the current transition step, which cycles through null, entering, entered, exiting, and exited states.

```javascript
import { useViewerContext } from "@react-instastories/base";
 
// Component that renders current step as string
function CurrentStep() {
  const viewer = useViewerContext();
 
  return viewer.transition.step; // null or "entering" -> "entered" -> "exiting" -> "exited"
}
 
// Examples of usage
<InstaStories>
  <Configurable.Container>
    <Configurable.Viewer>
      <CurrentStep />
    </Configurable.Viewer>
  </Configurable.Container>
  <Stories>
    <Story>
      <Preview>
        <CurrentStep />
      </Preview>
      <Pages>
        <Page>
          <CurrentStep />
        </Page>
      </Pages>
    </Story>
  </Stories>
</InstaStories>;
```

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

### usePreview()

Source: https://react-instastories.js.org/docs/base/contexts/preview

The usePreview hook provides methods and state to manage the visibility and interaction events of a Preview component.

```APIDOC
## usePreview()

### Description
A React hook for managing a Preview component, providing control over visibility and associated events.

### Properties
- **element** (HTMLElement) - The HTML element associated with the preview.
- **shown** (boolean) - The state for the visibility of the Preview component.
- **hide** ((target?: EventTarget & HTMLElement) => void) - Function to hide the Preview component.
- **show** (Function) - Function to show the Preview component.
- **...events** (PreviewEvents) - The events associated with the Preview component.
```

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

### useConfig()

Source: https://react-instastories.js.org/docs/base/hooks/config

The useConfig hook retrieves the current configuration object from the InstaStoriesContext. It must be used within components wrapped by the InstaStoriesContext provider.

```APIDOC
## useConfig()

### Description
Retrieves the current `Configuration` object from the `InstaStoriesContext`.

### Signature
`const config = useConfig();`

### Returns
- **config** (Object) - The current configuration settings object.

### Usage Example
```javascript
import { useConfig } from "@react-instastories/base";
import React from "react";

function DebugConfig() {
  const config = useConfig();

  React.useEffect(() => console.debug(config), [config]);

  return <pre>{JSON.stringify(config, null, 2)}</pre>;
}
```
```

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

### Preview Component API

Source: https://react-instastories.js.org/docs/base/preview

The Preview component allows users to render interactive elements that trigger story viewing. It accepts standard HTML attributes, custom component types, and specific event callbacks.

```APIDOC
## Preview Component

### Description
The `Preview` component renders an action element (defaulting to a button) that opens a story. It supports custom content, event handling, and state-based styling via CSS classes.

### Properties
- **as** (React.ElementType) - Optional - Specifies the component type to render (default: "button").
- **children** (React.ReactNode) - Optional - The content to be rendered inside the component.
- **className** (string) - Optional - Additional CSS class names to apply.
- **...events** (PreviewEvents) - Optional - Callback events for the component.
- **...props** (React.HTMLAttributes) - Optional - Standard HTML Element attributes.

### Events
- **onClick** (Function) - Optional - Called when the component is clicked. If it returns a truthy value, the viewer opening is prevented.
- **onShow** (Function) - Optional - Called when the preview is shown.
- **onHide** (Function) - Optional - Called when the preview is hidden.

### States
- **.instastories-preview--expanded** - Applied when the story is opened in the viewer. Sets `aria-expanded` to `true`.
```

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

### Implementing useMediaTimer with a Video Element

Source: https://react-instastories.js.org/docs/external/hooks/media-timer

Synchronizes a video element with the timer context by passing a ref to the hook.

```typescript
import { useMediaTimer } from "@react-instastories/external";
 
import React from "react";
 
function MediaContent() {
  const ref = React.useRef<HTMLVideoElement>(null);
  const timer = useMediaTimer(ref.current);
 
  return (
    <video ref={ref} autoPlay={true}>
      <source src="path/to/video.mp3" type="video/mp4" />
    </video>
  );
}
```

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

### Implement Page Component

Source: https://react-instastories.js.org/docs/base/page

Basic usage of the Page component with preload, priority, duration, and event callbacks.

```jsx
<Page
  preload
  priority
  duration={20000}
  onOpen={() => console.debug("Page opened!")}
  onClose={() => console.debug("Page closed!")}
>
  <h1>Page Content</h1>
</Page>
```

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

### Configure Immediately Animation

Source: https://react-instastories.js.org/docs/base/models/animation

Disables all animation logic for the fastest possible viewer opening. Recommended for performance-critical applications.

```jsx
<InstaStories config={{ animation: "immediately" }}>
  {...configurable}
  {...stories}
</InstaStories>
```

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

### Configuring Story Events and Controls

Source: https://react-instastories.js.org/docs/base/configurable

Configures story-level interactions including pointer events and page navigation controls.

```jsx
<Configurable.Container>
  <Configurable.Story
    events={[
      Events.Pointer.Timer,
      Events.Pointer.Close,
      Events.Pointer.Stories
    ]}
  >
    <Controls.Pages.Next />
    <Controls.Pages.Previous />
    <Controls.Indicator interactive threshold={1000} />
  </Configurable.Story>
</Configurable.Container>
```

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

### useStory()

Source: https://react-instastories.js.org/docs/base/hooks/story

A custom React hook that returns the current story context, including the story index and the associated HTMLElement.

```APIDOC
## useStory()

### Description
The `useStory` hook provides access to the current story context within a React component. It is designed for components that need to be aware of their position or associated element within a story-based interface.

### Returns
- **index** (number) - The index of the current story.
- **element** (HTMLElement | null) - The HTMLElement associated with the current story.

### Usage Example
```javascript
import { useStory } from "@react-instastories/base";
import React from "react";

function InnerStoryContent() {
  const story = useStory();

  return (
    <div>
      <p>Story Index: {story.index}</p>
      <p>Story Id Element: {story.element?.id}</p>
    </div>
  );
}
```
```

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

### InstaStories Component

Source: https://react-instastories.js.org/docs/base/instastories

The main component for rendering the library. It accepts configuration, children elements, and event callbacks.

```APIDOC
## InstaStories Component

### Description
The `InstaStories` component is the main component for rendering the library.

### Properties
- **config** (Configuration) - Optional - Configuration of the library component.
- **children** (React.ReactNode) - Optional - Children elements to be rendered inside the library component.
- **events** (ViewerEvents) - Optional - Callback events for the component.

### Events
- **onOpen** (Function) - Called when the viewer opens/mounts.
- **onShow** (Function) - Called when the viewer starts to show.
- **onHide** (Function) - Called when the viewer starts to hide.
- **onClose** (Function) - Called when the viewer closes/unmounts.
```

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

### Accessing page context with usePage

Source: https://react-instastories.js.org/docs/base/hooks/page

Import the hook from the base package and call it within a component to retrieve the current page's index and element.

```javascript
import { usePage } from "@react-instastories/base";
 
import React from "react";
 
function InnerPageContent() {
  const page = usePage();
 
  React.useEffect(() => console.debug(page), [page]);
 
  return (
    <div>
      <h1>Page Information</h1>
      <p>Page Index: {page.index}</p>
      <p>Page Id Element: {page.element?.id}</p>
    </div>
  );
}
```

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

### useKeyboardMovement(context)

Source: https://react-instastories.js.org/docs/external/hooks/keyboard-movement

A React hook that listens for keyboard events to trigger navigation functions provided in the context object.

```APIDOC
## useKeyboardMovement(context)

### Description
The `useKeyboardMovement` hook facilitates story or page navigation by binding keyboard events to navigation functions.

### Parameters
- **context** (Object) - Required - An object containing navigation functions.
  - **context.next** (Function) - Triggered on right arrow key press.
  - **context.previous** (Function) - Triggered on left arrow key press.

### Usage Example
```javascript
const stories = useStoriesContext();
useKeyboardMovement(stories);
```
```

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

### Usage of Custom Event in Configurable.Viewer

Source: https://react-instastories.js.org/docs/base/models/event

Demonstrates how to pass a custom event component to the events prop of Configurable.Viewer.

```jsx
<InstaStories>
  <Configurable.Container>
    <Configurable.Viewer events={[CustomEvent]} />
  </Configurable.Container>
  {...stories}
</InstaStories>
```

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

### Using the useStory hook

Source: https://react-instastories.js.org/docs/base/hooks/story

Import and call the useStory hook within a component to access the current story's element and index.

```javascript
import { useStory } from "@react-instastories/base";
 
import React from "react";
 
function InnerStoryContent() {
  const story = useStory();
 
  React.useEffect(() => console.debug(story), [story]);
 
  return (
    <div>
      <h1>Story Information</h1>
      <p>Story Index: {story.index}</p>
      <p>Story Id Element: {story.element?.id}</p>
    </div>
  );
}
```

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

### Basic Usage of Pages Component

Source: https://react-instastories.js.org/docs/base/pages

Wrap Page components or dynamic page content within the Pages component to render a story sequence.

```jsx
<Pages>
  <Page>{...content}</Page>
  <Page>{...content}</Page>
  <Page>{...content}</Page>
  {...pages}
</Pages>
```

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

### Enable Debug Mode

Source: https://react-instastories.js.org/docs/base/instastories

Globally enable debug mode for all InstaStories components by setting the config object.

```javascript
import { config } from "@react-instastories/base";
 
config.debug = true;
```

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

### Preloadable.Stories

Source: https://react-instastories.js.org/docs/external/preloadable

Component to manage the preloading of story elements.

```APIDOC
## Preloadable.Stories

### Description
Manages the preloading of story elements based on the current index.

### Properties
- **next** (number) - Optional - The number of stories to preload ahead of the current story (default: 1).
- **previous** (number) - Optional - The number of stories to preload behind the current story (default: 1).
- **unloadable** (boolean) - Optional - Whether stories outside the preload range can be unloaded (default: false).
```

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

### Preloadable.Pages

Source: https://react-instastories.js.org/docs/external/preloadable

Component to manage the preloading of page elements.

```APIDOC
## Preloadable.Pages

### Description
Manages the preloading of page elements based on the current index.

### Properties
- **next** (number) - Optional - The number of pages to preload ahead of the current page (default: 1).
- **previous** (number) - Optional - The number of pages to preload behind the current page (default: 1).
- **unloadable** (boolean) - Optional - Whether pages outside the preload range can be unloaded (default: false).
```

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

### Configuration Object

Source: https://react-instastories.js.org/docs/base/instastories

The configuration object used to customize the behavior of the InstaStories component, accessible via the useConfig hook.

```APIDOC
## Configuration

### Properties
- **animation** (Animation) - The animation type for opening state of viewer.
- **duration** (number) - The duration of each story in milliseconds by default.
- **preview** (object) - Configuration for the preview component.
  - **mounted** (boolean) - Mounts the preview on mounting main component.
- **timer** (object) - Timer configuration.
  - **shouldUseDefault** (boolean) - Enables/disables default in-built timer.
  - **interval** (number) - Timer interval.
- **viewer** (object) - Configuration for the viewer component.
  - **mounted** (boolean) - Mounts immediately active viewer on mounting the main component.
  - **props** (React.DialogHTMLAttributes) - Props for the active viewer component.
  - **story** (number) - The index of the story opened when mounted.
```

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

### Using useIndexes in a React component

Source: https://react-instastories.js.org/docs/external/hooks/indexes

Accesses the current story and page objects to display index information and view status.

```javascript
import { useIndexes } from "@react-instastories/base";
 
function InnerPageContent() {
  const { page, story } = useIndexes();
 
  return (
    <div>
      <p>Current Story: {story.index}</p>
      <p>Current Page: {page.index}</p>
      <p>
        {page.current
          ? "This is the current story and page."
          : "This is not the current story and page."}
      </p>
    </div>
  );
}
```

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

### useIndexes()

Source: https://react-instastories.js.org/docs/external/hooks/indexes

The useIndexes hook returns an object containing the current page and story information, allowing components to track their active state within a slideshow or story sequence.

```APIDOC
## useIndexes()

### Description
Returns the current story and page context for the component from which it is called.

### Return Values
- **page** (object) - Information about the page, containing `index` (number) and `current` (boolean).
- **story** (object) - Information about the story, containing `index` (number) and `current` (boolean).

### Usage Example
```javascript
import { useIndexes } from "@react-instastories/base";

function InnerPageContent() {
  const { page, story } = useIndexes();

  return (
    <div>
      <p>Current Story: {story.index}</p>
      <p>Current Page: {page.index}</p>
      <p>
        {page.current
          ? "This is the current story and page."
          : "This is not the current story and page."}
      </p>
    </div>
  );
}
```
```

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

### Extend standard presets

Source: https://react-instastories.js.org/docs/presets/how-to-create

Apply custom styles by extending existing presets using class names passed through component props.

```css
.documentation-example.instastories-viewer,
.documentation-example.instastories-stories {
  --is-preset-name: "example";
}
 
.documentation-example.instastories-viewer--entering,
.documentation-example.instastories-viewer--entered {
  background-color: #39f6;
}
 
/* ... any other CSS stylesheet ... */
```

```javascript
import "path/to/file/example.css";
 
<InstaStories
  config={{
    preview: { props: { className: "documentation-example" } },
    viewer: { props: { className: "documentation-example" } }
  }}
>
  {...content}
</InstaStories>;
```

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

### Using useInteractive to manage element state

Source: https://react-instastories.js.org/docs/external/hooks/interactive

Demonstrates how to disable interactive elements outside a container on mount and re-enable them on unmount.

```typescript
import { useInteractive } from "@react-instastories/external";
 
import React from "react";
 
function InteractiveInformation({
  interactiveOnlyContainer
}: {
  interactiveOnlyContainer: HTMLElement;
}) {
  const interactive = useInteractive();
  const [count, setCount] = React.useState(0);
 
  React.useEffect(() => {
    if (!interactiveOnlyContainer) return;
 
    const items = interactive.disable(interactiveOnlyContainer);
 
    setCount(items.length);
 
    return () => {
      interactive.enable(items);
 
      setCount(0);
    };
  }, [interactiveOnlyContainer]);
 
  return <p>Count of disabled items: {count}</p>;
}
```

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

### useStoriesContext()

Source: https://react-instastories.js.org/docs/base/contexts/stories

The useStoriesContext hook manages the state and behavior of stories, including navigation controls and configuration.

```APIDOC
## useStoriesContext()

### Description
A React hook that provides access to the stories context, allowing components to navigate between stories and update configuration.

### Properties
- **canNext** (boolean) - Indicates whether the next story can be shown.
- **canPrevious** (boolean) - Indicates whether the previous story can be shown.
- **children** (React.ReactNode) - The children elements of the stories.
- **config** (StoryConfiguration) - Configuration for the current story.
- **configure** (Function) - Function to update the current story configuration: `(config: StoryConfiguration) => void`.
- **current** (number) - The current story index.
- **length** (number) - The total number of stories.
- **mounted** (number) - Indicates that stories context was mounted.
- **next** (Function) - Function to show the next story.
- **previous** (Function) - Function to show the previous story.
- **show** (Function) - Function to show a specific story by index: `(index: number) => void`.
```

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

### useTimerContext

Source: https://react-instastories.js.org/docs/base/contexts/timer

A React hook for managing timer state and lifecycle.

```APIDOC
## useTimerContext

### Description
The `useTimerContext` hook is a React hook designed to manage an internal timer. It provides functionalities to start, pause, stop, and reset the timer, as well as manage its expiration and manual state.

### Properties
- **active** (boolean) - Indicates whether the timer is active.
- **manually** (boolean) - Indicates whether the timer is in manual state.
- **expired** (boolean) - Indicates whether the timer has expired.
- **duration** (number) - The expiration time in milliseconds.
- **time** (number) - The current time value.
- **stop** (Function) - Stops the timer and resets the time to 0.
- **pause** (Function) - Pauses the timer.
- **start** (Function) - Starts the timer.
- **reset** (Function) - Resets the timer by stopping and then starting it again.
- **change** ((expires: number, counter?: number) => void) - Changes the expiration time of the timer.
- **setManually** ((manually: boolean) => void) - Changes the manual state of the timer.
- **setWaiting** ((waiting: boolean) => void) - Changes the waiting state of the timer.

### Usage Example
```javascript
import { useTimerContext } from "@react-instastories/base";

function useTimerStringify() {
  const timer = useTimerContext();
  return JSON.stringify(timer);
}
```
```

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

### useViewerContext()

Source: https://react-instastories.js.org/docs/base/contexts/viewer

The useViewerContext hook manages the state and behavior of the viewer component, providing methods to control its visibility and lifecycle.

```APIDOC
## useViewerContext()

### Description
Manages the state and behavior of the viewer component, providing methods to control opening, closing, showing, and hiding.

### Returns
- **animation** (Animation) - Contains animation-related methods and values.
- **transition** (Transition) - Contains transition-related methods and values.
- **configurable** (Configurable) - Contains configurable-related methods and values.
- **mounted** (boolean) - Indicates whether the viewer is currently mounted in the DOM.
- **shown** (boolean) - Indicates whether the viewer is currently shown.
- **open** (Function) - Method to open the viewer.
- **close** (Function) - Method to close the viewer.
- **onOpen** (Function) - Callback triggered when the viewer opens. Returning a truthy value prevents the viewer from opening.
- **onShow** (Function) - Callback triggered when the viewer is shown. Returning a truthy value prevents the viewer from opening.
- **onClose** (Function) - Callback triggered when the viewer closes. Returning a truthy value prevents the viewer from opening.
- **onHide** (Function) - Callback triggered when the viewer is hidden. Returning a truthy value prevents the viewer from opening.
```

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

### usePagesContext

Source: https://react-instastories.js.org/docs/base/contexts/pages

The usePagesContext hook manages page state, including navigation controls and current index tracking.

```APIDOC
## usePagesContext

### Description
A React hook to manage page state and navigation, useful for implementing pagination or story-like features.

### Properties
- **canNext** (boolean) - Indicates whether the next page can be shown.
- **canPrevious** (boolean) - Indicates whether the previous page can be shown.
- **children** (React.ReactNode) - The children elements of the pages.
- **current** (number) - The current page index.
- **length** (number) - The total number of pages.
- **mounted** (number) - Indicates that pages context was mounted.
- **next** (Function) - Function to show the next page or story.
- **previous** (Function) - Function to show the previous page or story.
- **props** (PagesProps) - The props of the pages.
- **show** ((index: number) => void) - Function to show a specific page by index.
```

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

### Render Stories Component

Source: https://react-instastories.js.org/docs/base/stories

Basic implementation of the Stories component wrapping individual Story elements.

```jsx
<Stories>
  <Story>{...content}</Story>
  <Story>{...content}</Story>
  <Story>{...content}</Story>
  {...stories}
</Stories>
```

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

### Create a Custom Event Component

Source: https://react-instastories.js.org/docs/base/models/event

Defines a custom event component using EventProps to manage event listeners based on viewer context.

```typescript
import { type EventProps } from "@react-instastories/base";
 
import React from "react";
 
function CustomEvent({ children }: EventProps) {
  // Any own inner content of event for logic
  const viewer = useViewerContext();
 
  React.useEffect(() => {
    const handleEvent = (event: Event) => console.debug(event);
 
    if (viewer.shown) {
      window.addEventListener("blur", handleEvent);
      window.addEventListener("focus", handleEvent);
    } else {
      window.removeEventListener("blur", handleEvent);
      window.removeEventListener("focus", handleEvent);
    }
 
    return () => {
      window.removeEventListener("blur", handleEvent);
      window.removeEventListener("focus", handleEvent);
    };
  }, [viewer.shown]);
 
  // Add any own children, change or pass default children prop
  return children;
}
```

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

### useMediaTimer(mediaElement)

Source: https://react-instastories.js.org/docs/external/hooks/media-timer

A React hook that synchronizes a media element with the internal timer context.

```APIDOC
## useMediaTimer(mediaElement)

### Description
The `useMediaTimer` hook manages an internal timer from `@react-instastories/base` using HTML media controls. It synchronizes the playback state of a media element with the timer state.

### Parameters
- **mediaElement** (HTMLMediaElement | null) - Required - The reference to the HTML video or audio element to be synchronized.

### Returns
- **TimerContext** - The current timer state values.

### Usage Example
```javascript
import { useMediaTimer } from "@react-instastories/external";
import React from "react";

function MediaContent() {
  const ref = React.useRef(null);
  const timer = useMediaTimer(ref.current);

  return (
    <video ref={ref} autoPlay={true}>
      <source src="path/to/video.mp3" type="video/mp4" />
    </video>
  );
}
```
```

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

### Controls.Indicator

Source: https://react-instastories.js.org/docs/external/controls/indicator

The Indicator component displays a pagination indicator. It accepts properties to control interactivity and timing thresholds.

```APIDOC
## Controls.Indicator

### Description
A React component that displays a pagination indicator for a series of items, typically used within a story or slideshow context.

### Properties
- **interactive** (boolean) - Optional - Enables interactive mode for the indicator. Defaults to false.
- **threshold** (number) - Optional - The time in milliseconds before an action is performed once the indicator is full. Defaults to 1000.
- **...props** (React.HTMLAttributes) - Optional - Standard HTML Element attributes.

### Usage Example
```javascript
import { Configurable } from "@react-instastories/base";
import { Controls } from "@react-instastories/external";

function AppStories() {
  return (
    <Configurable.Container>
      <Configurable.Story>
        <Controls.Indicator interactive threshold={1000} />
      </Configurable.Story>
    </Configurable.Container>
  );
}
```
```

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

### Story Component

Source: https://react-instastories.js.org/docs/base/story

The Story component manages the lifecycle and rendering of a story, including page transitions and viewer events.

```APIDOC
## Story Component

### Description
The `Story` component manages and renders a single story with a preview and pages. It handles story transitions and provides hooks for viewer events.

### Properties
- **as** (React.ElementType) - Optional - Specifies the component type to render (default: "div").
- **duration** (number) - Optional - Duration of each page of the story in milliseconds.
- **preload** (boolean) - Optional - Determines whether the story should be preloaded (default: false).
- **start** (number) - Optional - Starting page index of the story when opened.
- **onOpen** (Function) - Optional - Callback triggered when the story is opened in the viewer. Returning a truthy value prevents hiding the Preview.
- **onClose** (Function) - Optional - Callback triggered when the story is closed in the viewer. Returning a truthy value prevents showing the Preview.

### Usage Example
```jsx
<Story
  preload
  duration={20000}
  start={1}
  onOpen={() => console.debug("Story opened!")}
  onClose={() => console.debug("Story closed!")}
>
  <Pages>
    <Page>Page with index #0</Page>
    <Page>Page with index #1</Page>
    <Page>Page with index #2</Page>
  </Pages>
</Story>
```
```

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

### usePage()

Source: https://react-instastories.js.org/docs/base/hooks/page

The usePage hook returns an object containing the current page's HTMLElement and index. It is designed for components that need to be aware of their position or associated element within a page-based interface.

```APIDOC
## usePage()

### Description
Provides access to the current page context, including the associated HTMLElement and the page index.

### Returns
- **index** (number) - The index of the current page.
- **element** (HTMLElement | null) - The HTMLElement associated with the current page.

### Usage Example
```javascript
import { usePage } from "@react-instastories/base";
import React from "react";

function InnerPageContent() {
  const page = usePage();

  return (
    <div>
      <p>Page Index: {page.index}</p>
      <p>Page Id Element: {page.element?.id}</p>
    </div>
  );
}
```
```

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

### usePagination(children: React.ReactNode)

Source: https://react-instastories.js.org/docs/base/hooks/pagination

The usePagination hook manages the state of pagination for a set of React nodes. It returns an interface containing navigation state and control functions.

```APIDOC
## usePagination(children)

### Description
Manages pagination state for a collection of React nodes. Returns an object containing the current index, total length, and navigation controls.

### Returns (Pagination Interface)
- **canNext** (boolean) - Indicates if there is a next element.
- **canPrevious** (boolean) - Indicates if there is a previous element.
- **current** (number) - The current element index.
- **length** (number) - The total number of elements.
- **change** ((index: number) => void) - Function to change the current element by index.

### Component Events (PaginationEvents)
- **onPaginate** ((index: number) => void) - Called when the element changes. Returning a truthy value prevents the change.
- **onNext** ((index: number) => void) - Called when moving to the next element. Returning a truthy value prevents the action.
- **onPrevious** ((index: number) => void) - Called when moving to the previous element. Returning a truthy value prevents the action.
```

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

### Using useTimerContext hook

Source: https://react-instastories.js.org/docs/base/contexts/timer

Access the timer context within a component to retrieve or stringify the current timer state.

```javascript
import { useTimerContext } from "@react-instastories/base";
 
function useTimerStringify() {
  const timer = useTimerContext();
 
  return JSON.stringify(timer);
}
```

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

### useInteractive

Source: https://react-instastories.js.org/docs/external/hooks/interactive

The useInteractive hook returns functions to control the interactivity of elements outside a specified container.

```APIDOC
## useInteractive

### Description
Provides functionality to manage interactive elements within a document by disabling and enabling elements outside a specified container.

### Return Values
- **disable** (function) - Accepts an `HTMLElement` and returns an array of `InteractiveElement` objects that were disabled.
- **enable** (function) - Accepts an array of `InteractiveElement` objects and re-enables them.

### Usage Example
```javascript
import { useInteractive } from "@react-instastories/external";

const interactive = useInteractive();

// Disable elements outside a container
const items = interactive.disable(containerElement);

// Re-enable elements
interactive.enable(items);
```
```

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

### Stories Component API

Source: https://react-instastories.js.org/docs/base/stories

The Stories component manages and renders a list of stories. It supports custom element types and standard HTML attributes.

```APIDOC
## Stories Component

### Description
The `Stories` component manages and renders a list of stories. It is forward-ref compatible and supports custom rendering elements.

### Properties
| Prop | Type | Description |
|---|---|---|
| `as` | `React.ElementType` | Specifies the component type to render (default: `div`). |
| `...events` | `PaginationEvents` | Optional callback events for component. |
| `...props` | `React.HTMLAttributes` | Standard HTML attributes for an HTML element. |

### Usage
```jsx
<Stories>
  <Story>{...content}</Story>
  <Story>{...content}</Story>
  <Story>{...content}</Story>
</Stories>
```
```
Tokens:
Raw