react-instagram-stories 1.0.4 → 1.1.0

package/README.md

@@ -5,71 +5,178 @@ A high-performance, fully customizable Instagram-style Stories component for Rea
 [![NPM Version](https://img.shields.io/npm/v/react-instagram-stories.svg)](https://www.npmjs.com/package/react-instagram-stories)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 
-## ✨ Features
-
-- 🎬 **Multiple Content Types**: Images, videos (with audio), text, and fully custom components
-- 🎨 **Fully Customizable**: Style every aspect of the stories
-- ⚡ **High Performance**: Optimized rendering with intelligent preloading
-- 📱 **Touch & Gestures**: Tap, swipe, and hold interactions
-- ⌨️ **Keyboard Navigation**: Full keyboard support for accessibility
-- 🎯 **TypeScript**: Complete type definitions included
-- ♿ **Accessible**: ARIA labels and keyboard navigation
-- 📦 **Lightweight**: Only **74.8 KB** with zero runtime dependencies
-- 🔄 **Auto Progress**: Smart progress bar that pauses during video buffering
-- 🎭 **Smooth Transitions**: Beautiful animations between stories and users
-- 🔌 **React Router Integration**: Built-in URL-based navigation support
-
-## 📦 Installation
+## Features
+
+- **Multiple Content Types**: Images, videos (with audio), text, and fully custom components
+- **Fully Customizable**: Style every aspect of the stories
+- **High Performance**: Optimized rendering with intelligent preloading
+- **Touch & Gestures**: Tap, swipe, and hold interactions
+- **Keyboard Navigation**: Full keyboard support for accessibility
+- **TypeScript**: Complete type definitions included
+- **Accessible**: ARIA labels and keyboard navigation
+- **Tailwind CSS Support**: Customize every sub-element via `classNames` prop with Tailwind or custom CSS classes
+- **3D Cube Transition**: Instagram-style 3D cube drag transition when switching between users
+- **Story Resume**: Dragging back to a previous user resumes their story from where you left off
+- **Lightweight**: ~30 KB with zero runtime dependencies
+- **No Router Required**: Works with native browser history API
+- **URL Navigation**: Built-in query parameter support (`?user=userId&story=storyId`)
+- **Auto Progress**: Smart progress bar that pauses during video buffering
+- **Smooth Transitions**: 3D cube drag transitions between users, smooth animations between stories
+
+## Installation
 
 ```bash
-npm install react-instagram-stories react-router-dom
+npm install react-instagram-stories
 # or
-yarn add react-instagram-stories react-router-dom
+yarn add react-instagram-stories
 # or
-pnpm add react-instagram-stories react-router-dom
+pnpm add react-instagram-stories
 ```
 
-**Note**: `react-router-dom` is required for URL-based story navigation.
+**Note**: No additional dependencies required! Works without react-router-dom.
 
-## 🚀 Quick Start
+## Quick Start
+
+### Simple Usage (Recommended)
+
+```tsx
+import { Stories, demoUsers } from "react-instagram-stories";
+import "react-instagram-stories/styles.css";
+
+function App() {
+  return <Stories users={demoUsers} />;
+}
+
+export default App;
+```
+
+That's it! Click on any avatar to open the story viewer. The URL automatically updates to `?user=userId&story=storyId` format.
+
+### Using Separate Components
 
 ```tsx
-import { BrowserRouter, Routes, Route } from 'react-router-dom';
-import { Stories, demoUsers } from 'react-instagram-stories';
-import 'react-instagram-stories/styles.css';
+import {
+  AvatarList,
+  StoryViewer,
+  demoUsers,
+  navigateWithParams,
+} from "react-instagram-stories";
+import "react-instagram-stories/styles.css";
 
 function App() {
+  const handleAvatarClick = (userIndex: number) => {
+    const user = demoUsers[userIndex];
+    // Navigate using user ID and story ID
+    navigateWithParams({ user: user.id, story: user.stories[0].id });
+  };
+
   return (
-    <BrowserRouter>
-      <Routes>
-        <Route path="/" element={<Stories users={demoUsers} />} />
-        <Route path="/story/:storyId" element={<Stories users={demoUsers} />} />
-      </Routes>
-    </BrowserRouter>
+    <div>
+      <h1>My App</h1>
+      <AvatarList users={demoUsers} onAvatarClick={handleAvatarClick} />
+      <StoryViewer users={demoUsers} />
+    </div>
   );
 }
+```
 
-export default App;
+## URL Navigation
+
+The StoryViewer supports URL-based navigation using query parameters with **user ID** and **story ID**:
+
+| URL                                | Result                              |
+| ---------------------------------- | ----------------------------------- |
+| `?user=user-travel&story=travel-1` | Opens Travel user's first story     |
+| `?user=user-polls&story=poll-1`    | Opens Interactive user's poll story |
+| `?user=user-launch&story=launch-2` | Opens Events user's second story    |
+| No query params                    | Viewer stays closed                 |
+
+### Navigation Helpers
+
+```tsx
+import { navigateWithParams, clearQueryParams } from "react-instagram-stories";
+
+// Open story viewer with user ID and story ID
+navigateWithParams({ user: "user-travel", story: "travel-1" });
+
+// Close story viewer (clear params)
+clearQueryParams();
 ```
 
-## 📖 API Reference
+## API Reference
 
 ### `<Stories />` Component
 
-The main component for displaying stories with avatar list and viewer.
+The all-in-one component with avatar list and story viewer.
+
+```tsx
+import { Stories } from "react-instagram-stories";
+
+<Stories users={myUsers} />;
+```
+
+| Prop         | Type                | Default      | Description                                                      |
+| ------------ | ------------------- | ------------ | ---------------------------------------------------------------- |
+| `users`      | `User[]`            | **required** | Array of user objects with their stories                         |
+| `classNames` | `StoriesClassNames` | -            | Object to customize sub-element CSS classes (Tailwind or custom) |
+
+### `<StoryViewer />` Component
+
+The story viewer component. Supports two modes:
+
+#### Query Param Mode (Default)
+
+When `isOpen` is not provided, reads from URL query params:
+
+```tsx
+<StoryViewer users={myUsers} />
+```
+
+#### Controlled Mode
+
+When `isOpen` is provided, you control the viewer state:
+
+```tsx
+<StoryViewer
+  users={myUsers}
+  isOpen={true}
+  initialUserIndex={0}
+  initialStoryIndex={0}
+  onClose={() => console.log("closed")}
+  onStoryChange={(userIndex, storyIndex) => console.log(userIndex, storyIndex)}
+/>
+```
 
-#### Props
+| Prop                | Type                              | Default      | Description                                                      |
+| ------------------- | --------------------------------- | ------------ | ---------------------------------------------------------------- |
+| `users`             | `User[]`                          | **required** | Array of user objects                                            |
+| `isOpen`            | `boolean`                         | -            | Controls viewer visibility (enables controlled mode)             |
+| `initialUserIndex`  | `number`                          | `0`          | Starting user index                                              |
+| `initialStoryIndex` | `number`                          | `0`          | Starting story index                                             |
+| `onClose`           | `() => void`                      | -            | Called when viewer closes                                        |
+| `onStoryChange`     | `(userIndex, storyIndex) => void` | -            | Called when story changes                                        |
+| `classNames`        | `StoryViewerClassNames`           | -            | Object to customize sub-element CSS classes (Tailwind or custom) |
 
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `users` | `User[]` | **required** | Array of user objects with their stories |
-| `closeNavigateTo` | `string` | `'/'` | Navigation path when stories viewer is closed |
+### `<AvatarList />` Component
+
+The horizontal scrollable avatar list.
+
+```tsx
+<AvatarList
+  users={myUsers}
+  onAvatarClick={(userIndex) => console.log(userIndex)}
+/>
+```
 
-### Story Types
+| Prop            | Type                          | Description                                                      |
+| --------------- | ----------------------------- | ---------------------------------------------------------------- |
+| `users`         | `User[]`                      | Array of user objects                                            |
+| `onAvatarClick` | `(userIndex: number) => void` | Called when avatar is clicked                                    |
+| `classNames`    | `AvatarListClassNames`        | Object to customize sub-element CSS classes (Tailwind or custom) |
 
-The component supports **4 core story types**:
+## Story Types
 
-#### 1. Image Story
+### 1. Image Story
 
 ```tsx
 {
@@ -81,7 +188,7 @@ The component supports **4 core story types**:
 }
 ```
 
-#### 2. Video Story
+### 2. Video Story
 
 ```tsx
 {
@@ -93,11 +200,12 @@ The component supports **4 core story types**:
 ```
 
 **Features:**
-- ✅ Audio enabled by default
-- ✅ Progress bar pauses during buffering
-- ✅ Auto-detects video duration
 
-#### 3. Text Story
+- Audio enabled by default
+- Progress bar pauses during buffering
+- Auto-detects video duration
+
+### 3. Text Story
 
 ```tsx
 {
@@ -110,9 +218,9 @@ The component supports **4 core story types**:
 }
 ```
 
-#### 4. Custom Component Story
+### 4. Custom Component Story
 
-The most powerful feature - add ANY custom React component as a story!
+Add ANY custom React component as a story!
 
 ```tsx
 const MyCustomStory: React.FC<StoryItemControls> = ({
@@ -140,23 +248,28 @@ const MyCustomStory: React.FC<StoryItemControls> = ({
 ```
 
 **Control Methods Available:**
+
 - `pause()` - Pause the story timer
 - `resume()` - Resume the story timer
 - `next()` - Go to next story
 - `prev()` - Go to previous story
 - `setDuration(ms: number)` - Update story duration dynamically
 
-## 💡 Custom Component Examples
+## Custom Component Examples
 
 Build interactive experiences! Here are examples included in `demoUsers`:
 
-### 📊 Poll Component
+### Poll Component
 
 ```tsx
-const PollComponent: React.FC<StoryItemControls> = ({ pause, resume, next }) => {
+const PollComponent: React.FC<StoryItemControls> = ({
+  pause,
+  resume,
+  next,
+}) => {
   const [selected, setSelected] = React.useState<number | null>(null);
   const [votes, setVotes] = React.useState([42, 28, 18, 12]);
-  const options = ['React', 'Vue', 'Angular', 'Svelte'];
+  const options = ["React", "Vue", "Angular", "Svelte"];
 
   React.useEffect(() => {
     pause(); // Pause timer during interaction
@@ -178,14 +291,16 @@ const PollComponent: React.FC<StoryItemControls> = ({ pause, resume, next }) =>
   const total = votes.reduce((a, b) => a + b, 0);
 
   return (
-    <div style={{
-      display: 'flex',
-      flexDirection: 'column',
-      height: '100%',
-      background: 'linear-gradient(135deg, #667eea 0%, #764ba2 100%)',
-      padding: '20px'
-    }}>
-      <h2 style={{ color: 'white', marginBottom: '20px' }}>
+    <div
+      style={{
+        display: "flex",
+        flexDirection: "column",
+        height: "100%",
+        background: "linear-gradient(135deg, #667eea 0%, #764ba2 100%)",
+        padding: "20px",
+      }}
+    >
+      <h2 style={{ color: "white", marginBottom: "20px" }}>
         What's your favorite framework?
       </h2>
       {options.map((option, index) => (
@@ -194,17 +309,18 @@ const PollComponent: React.FC<StoryItemControls> = ({ pause, resume, next }) =>
           onClick={() => handleVote(index)}
           disabled={selected !== null}
           style={{
-            margin: '8px 0',
-            padding: '15px',
-            background: selected === index ? '#4CAF50' : 'rgba(255,255,255,0.2)',
-            color: 'white',
-            border: 'none',
-            borderRadius: '12px',
-            fontSize: '16px',
-            cursor: selected !== null ? 'default' : 'pointer'
+            margin: "8px 0",
+            padding: "15px",
+            background:
+              selected === index ? "#4CAF50" : "rgba(255,255,255,0.2)",
+            color: "white",
+            border: "none",
+            borderRadius: "12px",
+            fontSize: "16px",
+            cursor: selected !== null ? "default" : "pointer",
           }}
         >
-          <div style={{ display: 'flex', justifyContent: 'space-between' }}>
+          <div style={{ display: "flex", justifyContent: "space-between" }}>
             <span>{option}</span>
             {selected !== null && (
               <span>{((votes[index] / total) * 100).toFixed(0)}%</span>
@@ -215,196 +331,35 @@ const PollComponent: React.FC<StoryItemControls> = ({ pause, resume, next }) =>
     </div>
   );
 };
-
-// Use it in your stories:
-{
-  id: 'poll-1',
-  type: 'custom_component',
-  component: PollComponent,
-  duration: 15000, // Extended duration for interaction
-}
 ```
 
-### 🧠 Quiz Component
-
-```tsx
-const QuizComponent: React.FC<StoryItemControls> = ({ pause, resume, next }) => {
-  const [selected, setSelected] = React.useState<number | null>(null);
-  const correctAnswer = 2; // Jupiter
-  const options = ['Mars', 'Saturn', 'Jupiter', 'Neptune'];
-
-  React.useEffect(() => {
-    pause();
-    return () => resume();
-  }, [pause, resume]);
-
-  const handleAnswer = (index: number) => {
-    setSelected(index);
-    setTimeout(() => {
-      resume();
-      next();
-    }, 2500);
-  };
+**Tip**: All these examples are included in `demoUsers`! Import and use them to see how they work.
 
-  return (
-    <div style={{ /* styles */ }}>
-      <h2>Which planet is the largest in our solar system?</h2>
-      {options.map((option, index) => (
-        <button
-          key={index}
-          onClick={() => handleAnswer(index)}
-          disabled={selected !== null}
-          style={{
-            background: selected === index
-              ? (index === correctAnswer ? '#4CAF50' : '#f44336')
-              : 'rgba(255,255,255,0.2)'
-          }}
-        >
-          {option}
-          {selected !== null && index === correctAnswer && ' ✓'}
-        </button>
-      ))}
-      {selected !== null && (
-        <p style={{ marginTop: '20px', fontWeight: 'bold' }}>
-          {selected === correctAnswer ? '🎉 Correct!' : '❌ Wrong! Jupiter is the largest.'}
-        </p>
-      )}
-    </div>
-  );
-};
-```
+## Styling
 
-### ⏱️ Countdown Component
+Import the default styles:
 
 ```tsx
-const CountdownComponent: React.FC<StoryItemControls> = () => {
-  const [timeLeft, setTimeLeft] = React.useState({
-    days: 12,
-    hours: 8,
-    minutes: 45,
-    seconds: 30,
-  });
-
-  React.useEffect(() => {
-    const timer = setInterval(() => {
-      setTimeLeft((prev) => {
-        let { days, hours, minutes, seconds } = prev;
-        seconds--;
-        if (seconds < 0) {
-          seconds = 59;
-          minutes--;
-        }
-        if (minutes < 0) {
-          minutes = 59;
-          hours--;
-        }
-        if (hours < 0) {
-          hours = 23;
-          days--;
-        }
-        return { days, hours, minutes, seconds };
-      });
-    }, 1000);
-
-    return () => clearInterval(timer);
-  }, []);
-
-  return (
-    <div style={{
-      display: 'flex',
-      flexDirection: 'column',
-      alignItems: 'center',
-      justifyContent: 'center',
-      height: '100%',
-      background: 'linear-gradient(135deg, #0f0c29 0%, #302b63 50%, #24243e 100%)',
-      padding: '20px'
-    }}>
-      <div style={{ fontSize: '48px', marginBottom: '15px' }}>🚀</div>
-      <h2 style={{ color: 'white', fontSize: '24px' }}>Product Launch</h2>
-      <p style={{ color: 'rgba(255,255,255,0.7)', marginBottom: '30px' }}>
-        Something amazing is coming...
-      </p>
-
-      <div style={{ display: 'flex', gap: '12px' }}>
-        {Object.entries(timeLeft).map(([key, value]) => (
-          <div key={key} style={{ textAlign: 'center' }}>
-            <div style={{
-              background: 'rgba(255,255,255,0.2)',
-              borderRadius: '12px',
-              padding: '15px 20px',
-              minWidth: '70px'
-            }}>
-              <div style={{ fontSize: '32px', fontWeight: 'bold', color: 'white' }}>
-                {String(value).padStart(2, '0')}
-              </div>
-            </div>
-            <div style={{ color: 'rgba(255,255,255,0.8)', fontSize: '12px', marginTop: '8px' }}>
-              {key.toUpperCase()}
-            </div>
-          </div>
-        ))}
-      </div>
-    </div>
-  );
-};
+import "react-instagram-stories/styles.css";
 ```
 
-### 🎚️ Slider Component
-
-```tsx
-const SliderComponent: React.FC<StoryItemControls> = ({ pause, resume }) => {
-  const [value, setValue] = React.useState(50);
-
-  React.useEffect(() => {
-    pause();
-    return () => resume();
-  }, [pause, resume]);
+**With Tailwind CSS**: Import the library styles **before** your Tailwind CSS so that utility classes can override them:
 
-  return (
-    <div style={{
-      display: 'flex',
-      flexDirection: 'column',
-      alignItems: 'center',
-      justifyContent: 'center',
-      height: '100%',
-      background: 'linear-gradient(135deg, #f093fb 0%, #f5576c 100%)',
-      padding: '40px'
-    }}>
-      <div style={{ fontSize: '48px', marginBottom: '20px' }}>🔥</div>
-      <h2 style={{ color: 'white', fontSize: '24px', marginBottom: '10px' }}>
-        How excited are you?
-      </h2>
+```css
+/* Your global CSS file */
+@import "react-instagram-stories/styles.css";
 
-      <div style={{ fontSize: '64px', margin: '30px 0' }}>{value}</div>
-
-      <input
-        type="range"
-        min="0"
-        max="100"
-        value={value}
-        onChange={(e) => setValue(Number(e.target.value))}
-        style={{
-          width: '80%',
-          height: '8px',
-          borderRadius: '4px',
-          appearance: 'none',
-          background: 'rgba(255,255,255,0.3)',
-          outline: 'none'
-        }}
-      />
-    </div>
-  );
-};
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
 ```
 
-**💡 Tip**: All these examples are included in `demoUsers`! Import and use them to see how they work.
-
-## 🎨 Styling
-
-Import the default styles:
+Or in JS, import the library CSS before your app's CSS:
 
 ```tsx
-import 'react-instagram-stories/styles.css';
+// main.tsx
+import "react-instagram-stories/styles.css"; // first
+import "./index.css"; // your Tailwind CSS — after
 ```
 
 Override with custom CSS:
@@ -425,24 +380,71 @@ Override with custom CSS:
 }
 
 /* Style avatars */
-.avatar-list {
+.story-avatar-list {
   padding: 20px;
   gap: 16px;
 }
 
-.avatar {
+.story-avatar-image-wrapper {
   width: 80px;
   height: 80px;
 }
 ```
 
-## 💡 Advanced Usage
+## Customization with classNames
+
+Every component accepts a `classNames` prop for fine-grained styling using Tailwind CSS or custom CSS classes. The prop is a typed object that maps to specific sub-elements.
+
+```tsx
+<Stories
+  users={users}
+  classNames={{
+    avatarList: {
+      root: "bg-gray-900 p-4",
+      avatar: { ring: "border-pink-500", username: "text-xs text-gray-400" },
+    },
+    storyViewer: {
+      overlay: "bg-black/90",
+      closeButton: "hover:text-gray-300",
+      progressBars: {
+        bar: { fill: "bg-gradient-to-r from-pink-500 to-purple-500" },
+      },
+    },
+  }}
+/>
+```
+
+You can also pass `classNames` directly to `StoryViewer` or `AvatarList` when using them separately:
+
+```tsx
+<AvatarList
+  users={users}
+  onAvatarClick={handleClick}
+  classNames={{
+    root: "bg-gray-900 p-4",
+    avatar: { ring: "border-pink-500", username: "text-xs text-gray-400" },
+  }}
+/>
+
+<StoryViewer
+  users={users}
+  classNames={{
+    overlay: "bg-black/90",
+    closeButton: "hover:text-gray-300",
+    progressBars: { bar: { fill: "bg-gradient-to-r from-pink-500 to-purple-500" } },
+  }}
+/>
+```
+
+All `classNames` types are exported from the package. See the [TypeScript Types](#typescript-types) section for the full list.
+
+## Advanced Usage
 
 ### Using Demo Data
 
 ```tsx
-import { Stories, demoUsers } from 'react-instagram-stories';
-import 'react-instagram-stories/styles.css';
+import { Stories, demoUsers } from "react-instagram-stories";
+import "react-instagram-stories/styles.css";
 
 function App() {
   return <Stories users={demoUsers} />;
@@ -454,7 +456,7 @@ The `demoUsers` includes examples of all story types including interactive polls
 ### Generate Demo Users
 
 ```tsx
-import { generateDemoUsers } from 'react-instagram-stories';
+import { generateDemoUsers } from "react-instagram-stories";
 
 const users = generateDemoUsers(10); // 10 users with random stories
 ```
@@ -462,39 +464,39 @@ const users = generateDemoUsers(10); // 10 users with random stories
 ### Create Custom Stories
 
 ```tsx
-import type { User } from 'react-instagram-stories';
+import type { User } from "react-instagram-stories";
 
 const myUsers: User[] = [
   {
-    id: '1',
-    username: 'johndoe',
-    avatarUrl: 'https://example.com/avatar.jpg',
+    id: "1",
+    username: "johndoe",
+    avatarUrl: "https://example.com/avatar.jpg",
     hasUnreadStories: true, // Shows ring around avatar
     stories: [
       {
-        id: 'story-1',
-        type: 'image',
-        src: 'https://example.com/photo.jpg',
-        alt: 'Beach sunset',
+        id: "story-1",
+        type: "image",
+        src: "https://example.com/photo.jpg",
+        alt: "Beach sunset",
         duration: 5000,
       },
       {
-        id: 'story-2',
-        type: 'video',
-        src: 'https://example.com/video.mp4',
+        id: "story-2",
+        type: "video",
+        src: "https://example.com/video.mp4",
         // duration auto-detected
       },
       {
-        id: 'story-3',
-        type: 'text',
-        text: 'Hello from my story!',
-        backgroundColor: '#FF6B6B',
-        textColor: '#FFFFFF',
+        id: "story-3",
+        type: "text",
+        text: "Hello from my story!",
+        backgroundColor: "#FF6B6B",
+        textColor: "#FFFFFF",
         duration: 5000,
       },
       {
-        id: 'story-4',
-        type: 'custom_component',
+        id: "story-4",
+        type: "custom_component",
         component: MyPollComponent,
         duration: 10000,
       },
@@ -503,13 +505,13 @@ const myUsers: User[] = [
 ];
 ```
 
-### Without React Router
+### Controlled Mode (Without URL)
 
-If you don't need URL navigation, use components directly:
+If you don't want URL navigation, use controlled mode:
 
 ```tsx
-import { useState } from 'react';
-import { AvatarList, StoryViewer } from 'react-instagram-stories';
+import { useState } from "react";
+import { AvatarList, StoryViewer } from "react-instagram-stories";
 
 function App() {
   const [viewerState, setViewerState] = useState({
@@ -521,7 +523,9 @@ function App() {
     <>
       <AvatarList
         users={myUsers}
-        onAvatarClick={(index) => setViewerState({ isOpen: true, userIndex: index })}
+        onAvatarClick={(index) =>
+          setViewerState({ isOpen: true, userIndex: index })
+        }
       />
       <StoryViewer
         users={myUsers}
@@ -534,20 +538,21 @@ function App() {
 }
 ```
 
-## ⌨️ Keyboard Controls
+## Keyboard Controls
 
 - `←` `→` - Navigate stories
 - `Space` - Pause/Resume
 - `Esc` - Close viewer
 
-## 🖱️ Mouse & Touch
+## Mouse & Touch
 
 - **Tap Left/Right** - Navigate stories
 - **Swipe Left/Right** - Change users
+- **Drag Left/Right** - 3D cube transition between users (peek at next/previous user, snaps on release)
 - **Swipe Down** - Close
 - **Hold/Hover** - Pause
 
-## 🎯 TypeScript Types
+## TypeScript Types
 
 ```tsx
 import type {
@@ -558,11 +563,18 @@ import type {
   ImageStoryItem,
   VideoStoryItem,
   TextStoryItem,
-  CustomComponentStoryItem
-} from 'react-instagram-stories';
+  CustomComponentStoryItem,
+  StoriesClassNames,
+  StoryViewerClassNames,
+  AvatarListClassNames,
+  AvatarClassNames,
+  StoryProgressBarsClassNames,
+  ProgressBarClassNames,
+  StoryItemClassNames,
+} from "react-instagram-stories";
 
 // Core Types
-type StoryItemType = 'image' | 'video' | 'text' | 'custom_component';
+type StoryItemType = "image" | "video" | "text" | "custom_component";
 
 interface StoryItemControls {
   pause: () => void;
@@ -579,16 +591,61 @@ interface User {
   stories: StoryItem[];
   hasUnreadStories?: boolean;
 }
+
+// ClassNames Types (for Tailwind / custom CSS customization)
+interface StoriesClassNames {
+  avatarList?: AvatarListClassNames;
+  storyViewer?: StoryViewerClassNames;
+}
+
+interface AvatarListClassNames {
+  root?: string;
+  avatar?: AvatarClassNames;
+}
+
+interface AvatarClassNames {
+  root?: string;
+  ring?: string;
+  image?: string;
+  username?: string;
+}
+
+interface StoryViewerClassNames {
+  overlay?: string;
+  closeButton?: string;
+  progressBars?: StoryProgressBarsClassNames;
+  storyItem?: StoryItemClassNames;
+}
+
+interface StoryProgressBarsClassNames {
+  root?: string;
+  bar?: ProgressBarClassNames;
+}
+
+interface ProgressBarClassNames {
+  root?: string;
+  fill?: string;
+}
+
+interface StoryItemClassNames {
+  root?: string;
+}
 ```
 
-## 📦 Package Exports
+## Package Exports
 
 ```tsx
-// Main component
-export { Stories } from 'react-instagram-stories';
+// Components
+import { Stories, StoryViewer, AvatarList } from "react-instagram-stories";
+
+// Navigation helpers
+import { navigateWithParams, clearQueryParams } from "react-instagram-stories";
+
+// Demo data
+import { demoUsers, generateDemoUsers } from "react-instagram-stories";
 
 // Types
-export type {
+import type {
   User,
   StoryItem,
   StoryItemControls,
@@ -596,52 +653,51 @@ export type {
   ImageStoryItem,
   VideoStoryItem,
   TextStoryItem,
-  CustomComponentStoryItem
-} from 'react-instagram-stories';
-
-// Utilities
-export { generateDemoUsers, demoUsers } from 'react-instagram-stories';
+  CustomComponentStoryItem,
+  StoriesClassNames,
+  StoryViewerClassNames,
+  AvatarListClassNames,
+  AvatarClassNames,
+  StoryProgressBarsClassNames,
+  ProgressBarClassNames,
+  StoryItemClassNames,
+} from "react-instagram-stories";
 
 // Styles
-import 'react-instagram-stories/styles.css';
+import "react-instagram-stories/styles.css";
 ```
 
-## 🚀 Performance
+## Performance
 
-- **Bundle Size**: 74.8 KB (20 KB gzipped)
-- **Zero Runtime Dependencies**
+- **Bundle Size**: ~30 KB (minified)
+- **Gzipped**: ~10 KB
+- **Zero Runtime Dependencies**: No production dependencies at all (framer-motion and tailwindcss-animate are dev-only)
 - **Smart Preloading**: Preloads adjacent stories
 - **Optimized Rendering**: Uses React.memo
 - **Video Buffering Detection**: Pauses progress during buffering
 
-## 📊 Package Info
-
-- **ESM**: 28.77 KB
-- **CJS**: 30.44 KB
-- **Gzipped**: ~20 KB
-- **Dependencies**: 0 (React is peer dep)
-
-## 🛠️ Tech Stack
+## Tech Stack
 
 - React 18+
 - TypeScript
-- React Router DOM (peer dependency)
+- CSS 3D Transforms (cube transition between users)
+- Native Browser History API (no router needed)
 - tsup (bundler)
 
-## 🤝 Contributing
+## Contributing
 
 Contributions welcome! Open an issue or PR.
 
-## 📄 License
+## License
 
 MIT © [Ankit Jangir](https://github.com/ankit64jangir)
 
-## 📞 Support
+## Support
 
-- 🐛 [Issues](https://github.com/ankit64jangir/react-instagram-stories/issues)
-- 💬 [Discussions](https://github.com/ankit64jangir/react-instagram-stories/discussions)
-- ⭐ [Star](https://github.com/ankit64jangir/react-instagram-stories)
+- [Issues](https://github.com/ankit64jangir/react-instagram-stories/issues)
+- [Discussions](https://github.com/ankit64jangir/react-instagram-stories/discussions)
+- [Star on GitHub](https://github.com/ankit64jangir/react-instagram-stories)
 
 ---
 
-Made with ❤️ by Ankit Jangir
+Made with love by Ankit Jangir