I built an Instagram Stories component for React — zero dependencies, fully interactive

#react #javascript #typescript #webdev

I spent two weeks building something I couldn't find anywhere else — an Instagram-style story viewer for React that actually feels like the real thing.

Live demo →

Try it before reading. Drag between users. Open it on your phone. You'll see why I'm writing this post.

The problem with existing solutions

Every library I found had at least one of these issues:

Required react-router as a peer dependency
No TypeScript support
Couldn't render custom React components as stories
No gesture support or janky swipe handling
Bloated bundle with heavy dependencies

So I built my own.

What you get in one install

npm install react-instagram-stories

import { Stories, demoUsers } from "react-instagram-stories";
import "react-instagram-stories/styles.css";

export default function App() {
  return <Stories users={demoUsers} />;
}

That's the entire setup. You get:

Scrollable avatar row with unread indicators
Full-screen story viewer
Progress bars that pause during video buffering
3D cube drag transition between users (the Instagram-feel detail)
URL navigation (?user=userId&story=storyId) — no router needed
Keyboard, touch, and mouse support
~30 KB bundle, zero runtime dependencies

The part I'm most proud of: custom component stories

You can drop any React component into a story slot and get full control over the timer:

const PollStory: React.FC<StoryItemControls> = ({ pause, resume, next }) => {
  const [voted, setVoted] = React.useState(false);

  React.useEffect(() => {
    pause(); // freeze progress while user interacts
    return () => resume();
  }, []);

  return (
    <div style={{ height: "100%", background: "#667eea", padding: 20 }}>
      <h2 style={{ color: "white" }}>Favorite framework?</h2>
      {["React", "Vue", "Svelte"].map((opt, i) => (
        <button key={i} onClick={() => { setVoted(true); setTimeout(next, 1500); }}>
          {opt}
        </button>
      ))}
    </div>
  );
};

// Use it in your stories array:
{ id: "poll-1", type: "custom_component", component: PollStory, duration: 30000 }

The demo ships with polls, quizzes, rating sliders, countdown timers, and product showcase cards — all built this way.

Gestures

Gesture	Action
Tap left / right	Prev / next story
Swipe left / right	Change user
Drag left / right	3D cube peek + snap
Swipe down	Close
Hold	Pause

Full TypeScript support

import type { User, StoryItemControls, StoriesClassNames } from "react-instagram-stories";

Every prop, component, and classNames key is typed.

DEV Community