Stepshots logoStepshots

React SDK

Embed interactive Stepshots demos in React and Next.js with the @stepshots/react component — typed props, autoplay, theming, and deep-linking to a step.

Overview

@stepshots/react is the first-class way to embed a published demo in a React or Next.js app. It's a small, typed component that renders the Stepshots player in a responsive container — the same player every other embedding method uses, wrapped in a React-friendly API.

Installation

bash
bun add @stepshots/react

It also installs cleanly with npm, pnpm, or yarn:

bash
npm install @stepshots/react

The package ships ESM and CommonJS builds plus TypeScript types, and declares react >= 18 as a peer dependency.

Quick Start

Pass the demoId of a published demo:

tsx
import { StepshotsDemo } from "@stepshots/react";

function App() {
  return <StepshotsDemo demoId="your-demo-id" />;
}

That's it — the component renders a responsive 16:9 player that fills its container width.

With Options

tsx
<StepshotsDemo
  demoId="your-demo-id"
  autoplay
  theme="dark"
  start={2}
  hideControls={false}
  width="800px"
  aspectRatio="16/9"
/>

Props

Prop Type Default Description
demoId string required The ID of the demo to embed.
baseUrl string "https://stepshots.com" Base URL of the Stepshots app. Override it to point at a self-hosted instance.
autoplay boolean false Auto-play the demo on load.
theme "light" | "dark" — Force a color theme. Omit to inherit the demo's default.
start number — Start at a specific step (1-indexed). Values ≤ 0 are ignored.
hideControls boolean false Hide the playback controls.
width string | number "100%" Container width — any CSS length or a number of pixels.
aspectRatio string "16/9" Container aspect ratio, as a CSS aspect-ratio value.
style React.CSSProperties — Extra inline styles merged onto the container.
className string — CSS class for the container.

Next.js

StepshotsDemo uses React hooks, so in the Next.js App Router it must run in a Client Component. Add the "use client" directive to the file that renders it:

tsx
"use client";

import { StepshotsDemo } from "@stepshots/react";

export function ProductTour() {
  return <StepshotsDemo demoId="your-demo-id" autoplay theme="dark" />;
}

You can then drop <ProductTour /> into any Server Component — pages, layouts, or MDX.

Sizing and styling

The component renders the player inside a relatively-positioned container with rounded corners. Control its footprint with width and aspectRatio, and use style or className for anything else:

tsx
<StepshotsDemo
  demoId="your-demo-id"
  width="100%"
  aspectRatio="4/3"
  className="my-demo"
  style={{ maxWidth: 960, margin: "0 auto" }}
/>

Deep-linking to a step

Use start to open the demo on a particular step — handy for docs that reference a specific moment in a flow. Steps are 1-indexed:

tsx
<StepshotsDemo demoId="your-demo-id" start={3} />

Self-hosted instances

If you run Stepshots on your own domain, point the component at it with baseUrl:

tsx
<StepshotsDemo demoId="your-demo-id" baseUrl="https://demos.example.com" />

TypeScript

The props interface is exported alongside the component:

tsx
import { StepshotsDemo, type StepshotsDemoProps } from "@stepshots/react";

const props: StepshotsDemoProps = { demoId: "your-demo-id", theme: "dark" };

How it works

Under the hood the component builds an embed URL — {baseUrl}/embed/{demoId} with autoplay, theme, start, and hide_controls query parameters — and renders it in a lazy-loaded, full-screen-capable iframe. It's the same player as the JS snippet, web component, and iframe embeds, so demos look and behave identically across every method.

  • Embedding Demos — all four embedding methods and when to use each.
  • API Keys — authenticate uploads and access.
Navigation