### Install react-native-instagram-stories

Source: https://github.com/birdwingo/react-native-instagram-stories/blob/main/_autodocs/troubleshooting.md

Use npm or yarn to install the package. For Expo projects, use the expo install command.

```bash
npm install @birdwingo/react-native-instagram-stories
# or
yarn add @birdwingo/react-native-instagram-stories
```

```bash
expo install @birdwingo/react-native-instagram-stories
```

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

### Install Optional Dependencies

Source: https://github.com/birdwingo/react-native-instagram-stories/blob/main/_autodocs/README.md

Install optional dependencies for features like progress persistence, video stories, or optimized list performance.

```bash
# Optional for progress persistence
npm install @react-native-async-storage/async-storage

# Optional for video stories
npm install react-native-video

# Optional for better avatar list performance
npm install @shopify/flash-list
```

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

### React Native Instagram Stories Full Usage Example

Source: https://github.com/birdwingo/react-native-instagram-stories/blob/main/_autodocs/api-reference/InstagramStories.md

Demonstrates the complete setup and usage of the InstagramStories component, including defining stories data, configuring props, and integrating with navigation buttons. Requires `@react-native-async-storage/async-storage` for progress saving.

```typescript
import React, { useRef } from 'react';
import { View, Pressable, Text } from 'react-native';
import InstagramStories, {
  InstagramStoriesPublicMethods,
  InstagramStoriesProps
} from '@birdwingo/react-native-instagram-stories';

const App = () => {
  const ref = useRef<InstagramStoriesPublicMethods>(null);

  const stories: InstagramStoriesProps['stories'] = [
    {
      id: 'user1',
      name: 'John Doe',
      avatarSource: { uri: 'https://example.com/john.jpg' },
      stories: [
        {
          id: 'story1',
          source: { uri: 'https://example.com/story1.jpg' }
        },
        {
          id: 'story2',
          source: { uri: 'https://example.com/story2.mp4' },
          mediaType: 'video'
        }
      ]
    },
    {
      id: 'user2',
      name: 'Jane Smith',
      avatarSource: { uri: 'https://example.com/jane.jpg' },
      stories: [
        {
          id: 'story3',
          source: { uri: 'https://example.com/story3.jpg' }
        }
      ]
    }
  ];

  return (
    <View style={{ flex: 1 }}>
      <InstagramStories
        ref={ref}
        stories={stories}
        saveProgress={true}
        avatarSize={60}
        showName={true}
        animationDuration={5000}
        onSwipeUp={(userId, storyId) => {
          console.log(`Swiped up on story ${storyId} by ${userId}`);
        }}
        onStoryStart={(userId, storyId) => {
          console.log(`Story ${storyId} started`);
        }}
        onStoryEnd={(userId, storyId) => {
          console.log(`Story ${storyId} ended`);
        }}
      />
      
      <Pressable onPress={() => ref.current?.show('user1')}>
        <Text>Show User 1 Stories</Text>
      </Pressable>
      
      <Pressable onPress={() => ref.current?.hide()}>
        <Text>Hide Stories</Text>
      </Pressable>
    </View>
  );
};

export default App;
```

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

### Install react-native-video for Video Stories

Source: https://github.com/birdwingo/react-native-instagram-stories/blob/main/_autodocs/troubleshooting.md

Install the react-native-video library for handling video playback within stories. Link it if using React Native versions below 0.60.

```bash
npm install react-native-video
# Link if using React Native < 0.60
react-native link react-native-video
```

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

### onStoryStart Callback Example

Source: https://github.com/birdwingo/react-native-instagram-stories/blob/main/_autodocs/configuration.md

This callback fires when a story begins its auto-play timer. Use it to start video analytics or emit custom events.

```typescript
onStoryStart?: (userId?: string, storyId?: string) => void
```

```typescript
<InstagramStories
  onStoryStart={(userId, storyId) => {
    console.log(`Story started: user=${userId}, story=${storyId}`);
  }}
/>
```

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

### Install Peer Dependencies

Source: https://github.com/birdwingo/react-native-instagram-stories/blob/main/_autodocs/troubleshooting.md

Install necessary peer dependencies for the library to function correctly.

```bash
npm install react-native-svg react-native-reanimated react-native-gesture-handler
```

```bash
expo install react-native-svg react-native-reanimated react-native-gesture-handler
```

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

### Install Core Dependencies

Source: https://github.com/birdwingo/react-native-instagram-stories/blob/main/_autodocs/README.md

Install the main library along with essential peer dependencies for React Native.

```bash
npm install @birdwingo/react-native-instagram-stories
npm install react-native-svg react-native-reanimated react-native-gesture-handler
```

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

### Install AsyncStorage

Source: https://github.com/birdwingo/react-native-instagram-stories/blob/main/_autodocs/troubleshooting.md

Install the @react-native-async-storage/async-storage package if you are using the saveProgress feature and it's not persisting.

```bash
npm install @react-native-async-storage/async-storage
```

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

### Install FlashList for Performance

Source: https://github.com/birdwingo/react-native-instagram-stories/blob/main/_autodocs/troubleshooting.md

Install the @shopify/flash-list package to potentially improve performance, especially with long lists of stories. This is often enabled automatically but verification is recommended.

```bash
npm install @shopify/flash-list
```

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

### StoryItemProps Example

Source: https://github.com/birdwingo/react-native-instagram-stories/blob/main/_autodocs/types.md

An example demonstrating how to create a StoryItemProps object with custom content and footer render functions.

```typescript
const storyItem: StoryItemProps = {
  id: 'story1',
  source: { uri: 'https://example.com/story.jpg' },
  mediaType: 'image',
  animationDuration: 5000,
  renderContent: () => (
    <View style={{ position: 'absolute', bottom: 20, left: 20 }}>
      <Text style={{ color: 'white' }}>Story Caption</Text>
    </View>
  ),
  renderFooter: () => (
    <View style={{ backgroundColor: 'rgba(0,0,0,0.5)', padding: 10 }}>
      <Text style={{ color: 'white' }}>Additional Info</Text>
    </View>
  )
};
```

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

### Complete Usage Example with Storage

Source: https://github.com/birdwingo/react-native-instagram-stories/blob/main/_autodocs/api-reference/StorageHelpers.md

Demonstrates how to integrate the InstagramStories component with storage helper functions for progress tracking. Enables automatic saving and manual control over story progress.

```typescript
import React, { useRef, useState } from 'react';
import { View, Pressable, Text } from 'react-native';
import InstagramStories,
  {
    InstagramStoriesPublicMethods
  } from '@birdwingo/react-native-instagram-stories';
import {
  getProgressStorage,
  setProgressStorage,
  clearProgressStorage
} from '@birdwingo/react-native-instagram-stories';

const StorageExample = () => {
  const ref = useRef<InstagramStoriesPublicMethods>(null);
  const [progress, setProgress] = useState<any>(null);

  const stories = [
    {
      id: 'user1',
      avatarSource: { uri: '...' },
      stories: [
        { id: 'story1', source: { uri: '...' } },
        { id: 'story2', source: { uri: '...' } }
      ]
    }
  ];

  const checkProgress = async () => {
    const currentProgress = await getProgressStorage();
    setProgress(currentProgress);
    console.log('Current progress:', currentProgress);
  };

  const markAsViewed = async (userId: string, storyId: string) => {
    const updated = await setProgressStorage(userId, storyId);
    setProgress(updated);
  };

  const resetAll = async () => {
    await clearProgressStorage();
    setProgress({});
  };

  return (
    <View>
      <InstagramStories
        ref={ref}
        stories={stories}
        saveProgress={true}  // Enable automatic progress tracking
      />

      <Pressable onPress={checkProgress}>
        <Text>Check Progress</Text>
      </Pressable>

      <Pressable onPress={() => markAsViewed('user1', 'story2')}>
        <Text>Mark Story 2 as Viewed</Text>
      </Pressable>

      <Pressable onPress={resetAll}>
        <Text>Reset All Progress</Text>
      </Pressable>

      {progress && (
        <Text>{JSON.stringify(progress, null, 2)}</Text>
      )}
    </View>
  );
};

export default StorageExample;

```

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

### Install Dependencies for Instagram Stories

Source: https://github.com/birdwingo/react-native-instagram-stories/blob/main/README.md

Install the necessary dependencies for the Instagram Stories component, including SVG, Reanimated, Gesture Handler, and the component itself.

```bash
npm install react-native-svg
npm install react-native-reanimated
npm install react-native-gesture-handler
npm install @birdwingo/react-native-instagram-stories
```

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

### Link Native Modules for iOS

Source: https://github.com/birdwingo/react-native-instagram-stories/blob/main/_autodocs/troubleshooting.md

Navigate to the ios directory and run pod install to link native modules for iOS builds.

```bash
cd ios && pod install && cd ..
```

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

### show

Source: https://github.com/birdwingo/react-native-instagram-stories/blob/main/README.md

Shows the stories modal. Optionally, you can provide a story ID to start displaying from that specific story.

```APIDOC
## show

### Description
Shows the stories modal. Optionally, you can provide a story ID to start displaying from that specific story.

### Method
`show`

### Parameters
#### Path Parameters
- **id** (string) - Optional - The ID of the story to start displaying.

### Response
This method does not return a value.
```

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

### Enable Progress Persistence

Source: https://github.com/birdwingo/react-native-instagram-stories/blob/main/_autodocs/configuration.md

Automatically save and resume viewed story progress using AsyncStorage. Requires `@react-native-async-storage/async-storage` to be installed.

```typescript
<InstagramStories
  stories={stories}
  saveProgress={true}
/>
```

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

### onShow Callback Example

Source: https://github.com/birdwingo/react-native-instagram-stories/blob/main/_autodocs/configuration.md

This callback is triggered when a story item becomes active and visible. Use it to track analytics or update the UI.

```typescript
onShow?: (id: string) => void
```

```typescript
<InstagramStories
  onShow={(storyId) => {
    console.log(`Story ${storyId} is now visible`);
    analytics.track('story_viewed', { storyId });
  }}
/>
```

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

### Mocking AsyncStorage for Testing

Source: https://github.com/birdwingo/react-native-instagram-stories/blob/main/_autodocs/api-reference/StorageHelpers.md

Provides an example of how to mock the AsyncStorage module using Jest for unit testing components that rely on storage helper functions. Ensures predictable behavior during tests.

```typescript
// Mock AsyncStorage for tests
import AsyncStorage from '@react-native-async-storage/async-storage';

jest.mock('@react-native-async-storage/async-storage', () => ({
  getItem: jest.fn(() => Promise.resolve(null)),
  setItem: jest.fn(() => Promise.resolve()),
  removeItem: jest.fn(() => Promise.resolve()),
}));

// In tests
await expect(getProgressStorage()).resolves.toEqual({});

```

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

### onStoryEnd Callback Example

Source: https://github.com/birdwingo/react-native-instagram-stories/blob/main/_autodocs/configuration.md

This callback is triggered when a story finishes animating. It's suitable for tracking completion or recording engagement metrics.

```typescript
onStoryEnd?: (userId?: string, storyId?: string) => void
```

```typescript
<InstagramStories
  onStoryEnd={(userId, storyId) => {
    console.log(`Story ended: user=${userId}, story=${storyId}`);
    // Record that user completed this story
  }}
/>
```

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

### Callback Parameters for Story Events

Source: https://github.com/birdwingo/react-native-instagram-stories/blob/main/_autodocs/types.md

Illustrates how to handle the `onStoryStart` callback, which provides the `userId` and `storyId` of the currently starting story. These parameters are optional strings.

```typescript
<InstagramStories
  onStoryStart={(userId, storyId) => {
    // userId and storyId are optional strings
    console.log(`Started: ${userId}/${storyId}`);
  }}
/>
```

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

### onSwipeUp Callback Example

Source: https://github.com/birdwingo/react-native-instagram-stories/blob/main/_autodocs/configuration.md

This callback is invoked when a user performs an upward swipe gesture on a story. Use it to open deep links or show calls to action.

```typescript
onSwipeUp?: (userId?: string, storyId?: string) => void
```

```typescript
<InstagramStories
  onSwipeUp={(userId, storyId) => {
    console.log(`Swipe up on user=${userId}, story=${storyId}`);
    navigation.navigate('Detail', { userId, storyId });
  }}
/>
```

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

### goToSpecificStory

Source: https://github.com/birdwingo/react-native-instagram-stories/blob/main/README.md

Changes the currently playing story to a specific story item by user ID and story index. If the index is out of bounds, it starts playing the first story for that user.

```APIDOC
## goToSpecificStory

### Description
Changes the currently playing story to a specific story item by user ID and story index. If the index is out of bounds, it starts playing the first story for that user.

### Method
`goToSpecificStory`

### Parameters
#### Path Parameters
- **userId** (string) - Required - The ID of the user whose stories to navigate to.
- **index** (number) - Required - The index of the story item to play.

### Response
This method does not return a value.
```

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

### Get Current Story Info

Source: https://github.com/birdwingo/react-native-instagram-stories/blob/main/_autodocs/api-reference/InstagramStories.md

Get the IDs of the currently displayed story and user.

```typescript
const current = ref.current?.getCurrentStory();
console.log(`Viewing story ${current?.storyId} by user ${current?.userId}`);
```

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

### Test AsyncStorage Functionality

Source: https://github.com/birdwingo/react-native-instagram-stories/blob/main/_autodocs/troubleshooting.md

Manually test AsyncStorage to ensure it is installed correctly and functioning by setting and retrieving a test item.

```typescript
// Manual test
import AsyncStorage from '@react-native-async-storage/async-storage';

await AsyncStorage.setItem('test', 'value');
const value = await AsyncStorage.getItem('test');
console.log(value); // Should log 'value'
```

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

### Accessing Ref Methods

Source: https://github.com/birdwingo/react-native-instagram-stories/blob/main/_autodocs/types.md

Demonstrates how to use a ref to access public methods of the InstagramStories component, such as showing a specific story, pausing playback, or getting the current story.

```typescript
const ref = useRef<InstagramStoriesPublicMethods>(null);

// Later in code
ref.current?.show('user1');
ref.current?.pause();
const current = ref.current?.getCurrentStory();
```

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

### Show Stories

Source: https://github.com/birdwingo/react-native-instagram-stories/blob/main/_autodocs/api-reference/InstagramStories.md

Display the story modal. If `id` is provided, it shows that user's stories starting from where they left off. If `id` is omitted, shows the first user's stories.

```typescript
// Show the first user's stories
ref.current?.show();

// Show a specific user's stories
ref.current?.show('user123');
```

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

### AsyncStorage Data Format Example

Source: https://github.com/birdwingo/react-native-instagram-stories/blob/main/_autodocs/api-reference/StorageHelpers.md

Illustrates the JSON structure used by AsyncStorage to store user story viewing progress. The key is the User ID and the value is the ID of the last viewed story.

```json
{
  "user1": "story3",
  "user2": "story1",
  "user3": "story5"
}

```

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

### Add Debug Logging for Story Events

Source: https://github.com/birdwingo/react-native-instagram-stories/blob/main/_autodocs/troubleshooting.md

Implement custom logging for story events like start, end, and display using the `onStoryStart`, `onStoryEnd`, and `onShow` props. This helps in debugging user interaction flows.

```typescript
// Add debug logging
<InstagramStories
  onStoryStart={(userId, storyId) => {
    console.log('START:', { userId, storyId });
  }}
  onStoryEnd={(userId, storyId) => {
    console.log('END:', { userId, storyId });
  }}
  onShow={(id) => {
    console.log('SHOW:', id);
  }}
/>
```

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

### Basic Usage of Instagram Stories Component

Source: https://github.com/birdwingo/react-native-instagram-stories/blob/main/README.md

Import and use the InstagramStories component in your React Native application. This example shows how to pass stories data and use a ref to access public methods.

```jsx
import React, { useRef } from 'react';
import { View } from 'react-native';
import InstagramStories, { InstagramStoriesPublicMethods } from '@birdwingo/react-native-instagram-stories';

const YourComponent = () => {

  // to use public methods:
  const ref = useRef( null ); // if using typescript - useRef<InstagramStoriesPublicMethods>( null )

  const stories = [{ // if using typescript - const stories: InstagramStoriesProps['stories']
    id: 'user1',
    name: 'User 1',
    avatarSource: { uri: 'user1-profile-image-url', },
    stories: [
      { id: 'story1', source: { uri: 'story1-image-url' } },
      { id: 'story2', source: { uri: 'story1-video-url' }, mediaType: 'video' },
      // ...
    ]}, // ...
  ];

  // usage of public method
  const setStories = () => ref.current?.setStories( stories );
  
  return (
    <View>
      <InstagramStories
        ref={ref}
        stories={stories}
        // ...
      />
     <Pressable onPress={setStories}>{...}</Pressable>
    </View>
  );
};

export default YourComponent;
```

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

### Import Storage Utilities

Source: https://github.com/birdwingo/react-native-instagram-stories/blob/main/_autodocs/README.md

Import functions for managing story progress persistence using AsyncStorage.

```typescript
import { 
  getProgressStorage,
  setProgressStorage,
  clearProgressStorage 
} from '@birdwingo/react-native-instagram-stories';
```

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

### Basic Instagram Stories Integration

Source: https://github.com/birdwingo/react-native-instagram-stories/blob/main/_autodocs/README.md

Demonstrates how to set up and render the InstagramStories component with sample data. Ensure you import necessary components and types.

```typescript
import React, { useRef } from 'react';
import { View } from 'react-native';
import InstagramStories, {
  InstagramStoriesPublicMethods
} from '@birdwingo/react-native-instagram-stories';

export default function App() {
  const ref = useRef<InstagramStoriesPublicMethods>(null);

  const stories = [
    {
      id: 'user1',
      avatarSource: { uri: 'https://example.com/avatar.jpg' },
      name: 'John Doe',
      stories: [
        { id: 'story1', source: { uri: 'https://example.com/image.jpg' } },
        { id: 'story2', source: { uri: 'https://example.com/video.mp4' }, mediaType: 'video' }
      ]
    }
  ];

  return (
    <View style={{ flex: 1 }}>
      <InstagramStories
        ref={ref}
        stories={stories}
        saveProgress={true}
      />
    </View>
  );
}
```

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

### goToNextStory

Source: https://github.com/birdwingo/react-native-instagram-stories/blob/main/README.md

Navigates to the next story item.

```APIDOC
## goToNextStory

### Description
Navigates to the next story item.

### Method
`goToNextStory`

### Parameters
This method takes no parameters.

### Response
This method does not return a value.
```

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

### Enable Hermes for Android

Source: https://github.com/birdwingo/react-native-instagram-stories/blob/main/_autodocs/troubleshooting.md

Configure the android/app/build.gradle file to enable Hermes for improved performance on Android.

```gradle
project.ext.react = {
  enableHermes: true,
}
```

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

### onHide Callback Example

Source: https://github.com/birdwingo/react-native-instagram-stories/blob/main/_autodocs/configuration.md

This callback is invoked when a story item is no longer active or visible. It's useful for pausing media or resetting state.

```typescript
onHide?: (id: string) => void
```

```typescript
<InstagramStories
  onHide={(storyId) => {
    console.log(`Story ${storyId} is now hidden`);
  }}
/>
```

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

### goToSpecificStory

Source: https://github.com/birdwingo/react-native-instagram-stories/blob/main/_autodocs/api-reference/InstagramStories.md

Jumps directly to a specific story index for a given user. If the index does not exist, it shows the first story of that user.

```APIDOC
## goToSpecificStory

### Description
Jump directly to a specific story index for a given user. If the index doesn't exist, shows the first story of that user.

### Method
`goToSpecificStory: (userId: string, index?: number) => void`

### Parameters
#### Path Parameters
- `userId` (string) - Required - User ID to navigate to
- `index` (number) - Optional - Story index (0-based) within that user's stories

### Request Example
```typescript
// Show first story of user 'user123'
ref.current?.goToSpecificStory('user123');

// Show second story of user 'user123'
ref.current?.goToSpecificStory('user123', 1);
```
```

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

### show

Source: https://github.com/birdwingo/react-native-instagram-stories/blob/main/_autodocs/api-reference/InstagramStories.md

Displays the stories for a specific user. This method allows programmatic control over which user's stories are shown.

```APIDOC
## show

### Description
Shows the stories for a given user ID.

### Method
`show(userId: string) => void`

### Parameters
#### Path Parameters
- **userId** (string) - Required - The ID of the user whose stories should be displayed.

### Request Example
```javascript
ref.current?.show('user1');
```

### Response
None
```

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

### Clear Cache and Reinstall Dependencies

Source: https://github.com/birdwingo/react-native-instagram-stories/blob/main/_autodocs/troubleshooting.md

Remove node_modules and package-lock.json, then reinstall all dependencies to resolve potential conflicts.

```bash
rm -rf node_modules package-lock.json
npm install
```

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

### goToPreviousStory

Source: https://github.com/birdwingo/react-native-instagram-stories/blob/main/README.md

Navigates to the previous story item.

```APIDOC
## goToPreviousStory

### Description
Navigates to the previous story item.

### Method
`goToPreviousStory`

### Parameters
This method takes no parameters.

### Response
This method does not return a value.
```

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

### Public Methods (via ref)

Source: https://github.com/birdwingo/react-native-instagram-stories/blob/main/_autodocs/README.md

Programmatically control the Instagram Stories component using a ref.

```APIDOC
## Public Methods (via ref)

Access these using `useRef<InstagramStoriesPublicMethods>(null)`:

| Method | Signature | Description |
|--------|-----------|-------------|
| `show` | (id?: string) => void | Display modal with optional user ID |
| `hide` | () => void | Close modal |
| `pause` | () => void | Pause current story |
| `resume` | () => void | Resume from pause |
| `isPaused` | () => boolean | Check pause state |
| `goToNextStory` | () => void | Advance to next story |
| `goToPreviousStory` | () => void | Go back to previous |
| `getCurrentStory` | () => {userId?, storyId?} | Get active story IDs |
| `goToSpecificStory` | (userId: string, index?: number) => void | Jump to specific story |
| `setStories` | (stories: InstagramStoryProps[]) => void | Replace all stories |
| `spliceStories` | (stories: InstagramStoryProps[], index?: number) => void | Insert stories |
| `spliceUserStories` | (stories: StoryItemProps[], user: string, index?: number) => void | Insert user stories |
| `clearProgressStorage` | () => void | Clear viewed history |
```

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

### Pre-load Images for Faster Modal Opening

Source: https://github.com/birdwingo/react-native-instagram-stories/blob/main/_autodocs/troubleshooting.md

Improve modal opening speed by pre-fetching images using React Native's Image.prefetch before they are needed.

```typescript
// Manually prefetch
import { Image } from 'react-native';

stories.forEach(user => {
  user.stories.forEach(story => {
    if (story.source?.uri) {
      Image.prefetch(story.source.uri);
    }
  });
});
```

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

### Get Story Viewing Progress

Source: https://github.com/birdwingo/react-native-instagram-stories/blob/main/_autodocs/api-reference/StorageHelpers.md

Retrieve all saved story viewing progress from AsyncStorage. Returns an empty object if no progress is saved or an error occurs. Errors are logged internally and the function always returns a promise.

```typescript
import { getProgressStorage } from '@birdwingo/react-native-instagram-stories';

const progress = await getProgressStorage();
// Returns: { 'user1': 'story3', 'user2': 'story1' }

Object.entries(progress).forEach(([userId, lastStoryId]) => {
  console.log(`User ${userId} last viewed story ${lastStoryId}`);
});
```

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

### Custom Component Rendering

Source: https://github.com/birdwingo/react-native-instagram-stories/blob/main/_autodocs/types.md

Shows how to define a story item with custom render functions for overlay content and the footer, allowing for flexible UI customization.

```typescript
const story: StoryItemProps = {
  id: 'story1',
  source: { uri: '...' },
  renderContent: () => <CustomOverlay />,
  renderFooter: () => <CustomFooter />
};
```

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

### Immutably Update Stories Array

Source: https://github.com/birdwingo/react-native-instagram-stories/blob/main/_autodocs/troubleshooting.md

When updating stories, create new array references to ensure the component re-renders and displays the changes. This example shows how to immutably add a new story to a user's story list.

```typescript
// Immutably update
const updated = [
  ...stories.slice(0, index),
  { ...stories[index], stories: [...stories[index].stories, newStory] },
  ...stories.slice(index + 1)
];
ref.current?.setStories(updated);
```

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

### Importing Constants

Source: https://github.com/birdwingo/react-native-instagram-stories/blob/main/_autodocs/configuration.md

Import constants from the library to configure default durations, colors, and storage keys. Ensure the correct path is used for imports.

```typescript
import {
  ANIMATION_DURATION,
  DEFAULT_COLORS,
  AVATAR_SIZE
} from '@birdwingo/react-native-instagram-stories/lib/core/constants';
```

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

### Handle Deep Linking and Navigation

Source: https://github.com/birdwingo/react-native-instagram-stories/blob/main/_autodocs/usage-patterns.md

Use the onSwipeUp prop to trigger navigation within your app or open external URLs based on story interactions. Map story IDs to navigation routes or URLs.

```typescript
import React, { useRef } from 'react';
import { View } from 'react-native';
import { useNavigation } from '@react-navigation/native';
import InstagramStories, {
  InstagramStoriesPublicMethods
} from '@birdwingo/react-native-instagram-stories';

const DeepLinkStories = () => {
  const navigation = useNavigation();
  const ref = useRef<InstagramStoriesPublicMethods>(null);

  // Map story IDs to deep links
  const storyLinks = {
    story1: { screen: 'ProductDetail', params: { productId: '123' } },
    story2: { screen: 'ProfileDetail', params: { userId: 'user456' } },
    story3: { url: 'https://example.com/offer' }
  };

  const handleSwipeUp = (userId?: string, storyId?: string) => {
    if (!storyId) return;

    const link = storyLinks[storyId as keyof typeof storyLinks];

    if (link) {
      if ('screen' in link) {
        // Navigate within app
        navigation.navigate(link.screen, link.params);
      } else if ('url' in link) {
        // Open external URL
        // Use Linking or react-native-web-browser
        // Linking.openURL(link.url);
      }
    }
  };

  const stories = [
    // ... your stories
  ];

  return (
    <View style={{ flex: 1 }}>
      <InstagramStories
        ref={ref}
        stories={stories}
        onSwipeUp={handleSwipeUp}
      />
    </View>
  );
};

export default DeepLinkStories;
```

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

### Configure Video Props for Stories

Source: https://github.com/birdwingo/react-native-instagram-stories/blob/main/_autodocs/troubleshooting.md

Customize video playback behavior, error handling, and load events using the videoProps prop for InstagramStories.

```typescript
<InstagramStories
  videoProps={{
    controls: false,
    progressUpdateInterval: 250,
    onError: (error) => console.log('Video error:', error),
    onLoad: (data) => console.log('Video loaded:', data)
  }}
/>
```

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

### Pressable Gesture Configuration

Source: https://github.com/birdwingo/react-native-instagram-stories/blob/main/_autodocs/architecture.md

Configures tap gestures for advancing or going back through stories, pausing, and resuming. It uses onPress, onLongPress, and onPressOut events.

```typescript
Pressable
  .onPress()      // Advance/previous based on X position
  .onLongPress()  // Pause and hide elements
  .onPressOut()   // Resume
```

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

### Component Hierarchy Overview

Source: https://github.com/birdwingo/react-native-instagram-stories/blob/main/_autodocs/architecture.md

Illustrates the nested structure of components within the library, from the main InstagramStories component down to individual elements like images and progress bars.

```plaintext
InstagramStories (forwardRef)
├── StoryAvatarList
│   ├── ScrollView or FlashList (conditional)
│   └── StoryAvatar (per user)
│       ├── Loader (animated SVG spinner)
│       └── Image (profile picture)
└── StoryModal (forwardRef)
    ├── GestureDetector (Pan gesture handler)
    ├── Pressable (tap handler)
    └── StoryList (per user, animated)
        ├── StoryAnimation (3D cube perspective)
        │   ├── StoryImage (or StoryVideo)
        │   │   ├── Image component
        │   │   └── Loader
        │   └── Overlay content
        ├── Progress (progress bars)
        ├── StoryHeader
        │   ├── User avatar
        │   ├── User name
        │   └── Close button
        ├── StoryContent (custom renderContent)
        └── StoryFooter (custom renderFooter)
```

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

### Control Instagram Stories Component with Ref Methods

Source: https://github.com/birdwingo/react-native-instagram-stories/blob/main/_autodocs/usage-patterns.md

Demonstrates comprehensive control over the Instagram Stories component using its public ref methods. This includes showing, hiding, pausing, resuming, and navigating through stories.

```typescript
import React, { useRef } from 'react';
import { View, Pressable, Text, ScrollView } from 'react-native';
import InstagramStories,
  {
    InstagramStoriesPublicMethods
  } from '@birdwingo/react-native-instagram-stories';

const RefControlExample = () => {
  const ref = useRef<InstagramStoriesPublicMethods>(null);

  const stories = [
    {
      id: 'user1',
      avatarSource: { uri: 'https://example.com/avatar1.jpg' },
      stories: [
        { id: 'story1', source: { uri: 'https://example.com/image1.jpg' } },
        { id: 'story2', source: { uri: 'https://example.com/image2.jpg' } },
        { id: 'story3', source: { uri: 'https://example.com/image3.jpg' } }
      ]
    },
    {
      id: 'user2',
      avatarSource: { uri: 'https://example.com/avatar2.jpg' },
      stories: [
        { id: 'story4', source: { uri: 'https://example.com/image4.jpg' } }
      ]
    }
  ];

  const controls = [
    {
      label: 'Show All',
      action: () => ref.current?.show()
    },
    {
      label: 'Show User 1',
      action: () => ref.current?.show('user1')
    },
    {
      label: 'Show User 2',
      action: () => ref.current?.show('user2')
    },
    {
      label: 'Hide',
      action: () => ref.current?.hide()
    },
    {
      label: 'Pause',
      action: () => ref.current?.pause()
    },
    {
      label: 'Resume',
      action: () => ref.current?.resume()
    },
    {
      label: 'Next',
      action: () => ref.current?.goToNextStory()
    },
    {
      label: 'Previous',
      action: () => ref.current?.goToPreviousStory()
    },
    {
      label: 'Go to User 1, Story 3',
      action: () => ref.current?.goToSpecificStory('user1', 2)
    },
    {
      label: 'Is Paused?',
      action: () => console.log(ref.current?.isPaused())
    },
    {
      label: 'Get Current',
      action: () => console.log(ref.current?.getCurrentStory())
    }
  ];

  return (
    <View style={{ flex: 1 }}>
      <InstagramStories ref={ref} stories={stories} />

      <ScrollView style={{ flex: 1, padding: 16 }}>
        {controls.map((control, index) => (
          <Pressable
            key={index}
            onPress={control.action}
            style={{
              padding: 12,
              marginVertical: 6,
              backgroundColor: '#4ECDC4',
              borderRadius: 8
            }}>
            <Text style={{ color: 'white', fontWeight: '600' }}>
              {control.label}
            </Text>
          </Pressable>
        ))}
      </ScrollView>
    </View>
  );
};

export default RefControlExample;
```

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

### goToNextStory

Source: https://github.com/birdwingo/react-native-instagram-stories/blob/main/_autodocs/api-reference/InstagramStories.md

Advances to the next story in the current user's stories. If at the end of the current user's stories, it moves to the first story of the next user, depending on the `loopingStories` prop.

```APIDOC
## goToNextStory

### Description
Advance to the next story in the current user's stories, or to the first story of the next user if at the end of current user's stories. Behavior depends on `loopingStories` prop.

### Method
`goToNextStory: () => void`

### Request Example
```typescript
ref.current?.goToNextStory();
```
```

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

### Configure Modal and Media Styling

Source: https://github.com/birdwingo/react-native-instagram-stories/blob/main/_autodocs/configuration.md

Apply custom styles to the story modal container, media display area, and header elements. Adjust aspect ratios for images and control the background color of the modal.

```typescript
<InstagramStories
  stories={stories}
  backgroundColor="#1a1a1a"
  imageStyles={{ aspectRatio: 0.5626 }}
  headerStyle={{ paddingHorizontal: 16, paddingTop: 8 }}
  progressContainerStyle={{ paddingHorizontal: 8, paddingVertical: 12 }}
  textStyle={{ fontSize: 14, fontWeight: 'bold', color: '#fff' }}
/>
```

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

### Implement Deep Linking with onSwipeUp

Source: https://github.com/birdwingo/react-native-instagram-stories/blob/main/_autodocs/README.md

Handle deep linking by defining a function for the `onSwipeUp` callback. This function can navigate to different screens or external links based on `userId` and `storyId`.

```typescript
const handleSwipeUp = (userId?: string, storyId?: string) => {
  // Open product, profile, or external link
  navigation.navigate('Detail', { userId, storyId });
};

<InstagramStories
  onSwipeUp={handleSwipeUp}
  stories={stories}
/>
```

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

### LoopingStoriesOption

Source: https://github.com/birdwingo/react-native-instagram-stories/blob/main/_autodocs/types.md

Defines the behavior options for looping through stories.

```APIDOC
## Looping Stories Options

### Description
Type for `loopingStories` prop behavior.

### Values
#### `'none'`
- **Behavior**: Modal closes after viewing all stories.

#### `'all'`
- **Behavior**: Stories loop from beginning after reaching the end.

#### `'onlyLast'`
- **Behavior**: Stories loop on the last user only.

### Type Definition
```typescript
type LoopingStoriesOption = 'none' | 'all' | 'onlyLast';
```
```

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

### Manage Story Viewing Progress

Source: https://github.com/birdwingo/react-native-instagram-stories/blob/main/_autodocs/usage-patterns.md

Handles story progress persistence and cleanup. Use `saveProgress={true}` to enable persistence. Call `clearProgressStorage` to reset progress and `getProgressStorage` to retrieve current progress.

```typescript
import React, { useRef } from 'react';
import { View, Pressable, Text } from 'react-native';
import InstagramStories,
  {
    InstagramStoriesPublicMethods
  } from '@birdwingo/react-native-instagram-stories';
import { getProgressStorage } from '@birdwingo/react-native-instagram-stories';

const ProgressManagement = () => {
  const ref = useRef<InstagramStoriesPublicMethods>(null);

  const stories = [
    // ... your stories
  ];

  const handleClearProgress = async () => {
    await ref.current?.clearProgressStorage();
    console.log('All viewing progress cleared');
  };

  const handleCheckProgress = async () => {
    const progress = await getProgressStorage();
    console.log('Current progress:', progress);
    // progress = { user1: 'story3', user2: 'story1' }
  };

  const handleResetAndShow = async () => {
    await ref.current?.clearProgressStorage();
    ref.current?.show(); // Show from beginning
  };

  return (
    <View style={{ flex: 1 }}>
      <InstagramStories
        ref={ref}
        stories={stories}
        saveProgress={true}
      />

      <Pressable onPress={handleCheckProgress}>
        <Text>Check Progress</Text>
      </Pressable>

      <Pressable onPress={handleClearProgress}>
        <Text>Clear All Progress</Text>
      </Pressable>

      <Pressable onPress={handleResetAndShow}>
        <Text>Reset & Show from Start</Text>
      </Pressable>
    </View>
  );
};

export default ProgressManagement;
```

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

### Configure Image Props for Stories

Source: https://github.com/birdwingo/react-native-instagram-stories/blob/main/_autodocs/troubleshooting.md

Customize image loading behavior and error handling using the imageProps prop for InstagramStories.

```typescript
<InstagramStories
  imageProps={{
    onError: (error) => console.log('Image error:', error),
    progressiveRenderingEnabled: true
  }}
/>
```

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

### Video Stories Integration

Source: https://github.com/birdwingo/react-native-instagram-stories/blob/main/_autodocs/usage-patterns.md

Integrate video content into stories, specifying playback properties and global duration limits. Ensure videos are correctly formatted and provide fallback images.

```typescript
import React from 'react';
import { View } from 'react-native';
import InstagramStories from '@birdwingo/react-native-instagram-stories';

const VideoStories = () => {
  const stories = [
    {
      id: 'user1',
      avatarSource: { uri: 'https://example.com/avatar1.jpg' },
      name: 'Video Story User',
      stories: [
        {
          id: 'videoStory1',
          source: { uri: 'https://example.com/video1.mp4' },
          mediaType: 'video',
          animationDuration: 5000 // Max 5 seconds
        },
        {
          id: 'imageAfterVideo',
          source: { uri: 'https://example.com/image1.jpg' },
          mediaType: 'image'
        },
        {
          id: 'videoStory2',
          source: { uri: 'https://example.com/video2.mp4' },
          mediaType: 'video'
          // No animationDuration - will play until completion
        }
      ]
    }
  ];

  return (
    <View style={{ flex: 1 }}>
      <InstagramStories
        stories={stories}
        videoProps={{
          controls: false,
          repeat: false,
          rate: 1.0,
          volume: 1.0,
          muted: false,
          progressUpdateInterval: 250
        }}
        videoAnimationMaxDuration={30000} // Global max for all videos
        loaderColor="#4ECDC4"
      />
    </View>
  );
};

export default VideoStories;
```

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

### Dynamically Update Stories

Source: https://github.com/birdwingo/react-native-instagram-stories/blob/main/_autodocs/usage-patterns.md

Demonstrates how to add new users, add stories to existing users, or replace all stories using the component's ref methods. Use `spliceStories` to add new users or `spliceUserStories` to add stories to a specific user. `setStories` can be used to replace the entire story collection.

```typescript
import React, { useRef, useState } from 'react';
import { View, Pressable, Text } from 'react-native';
import InstagramStories,
  {
    InstagramStoriesPublicMethods,
    InstagramStoriesProps
  } from '@birdwingo/react-native-instagram-stories';

const DynamicStories = () => {
  const ref = useRef<InstagramStoriesPublicMethods>(null);
  const [stories, setStories] = useState<InstagramStoriesProps['stories']>([
    {
      id: 'user1',
      avatarSource: { uri: 'https://example.com/avatar1.jpg' },
      stories: [
        { id: 'story1', source: { uri: 'https://example.com/image1.jpg' } }
      ]
    }
  ]);

  const addNewStories = () => {
    const newStory = {
      id: `user${Math.random()}`,
      avatarSource: { uri: 'https://example.com/new-avatar.jpg' },
      name: 'New User',
      stories: [
        { id: 'newStory1', source: { uri: 'https://example.com/new-image.jpg' } }
      ]
    };

    // Method 1: Replace entire array
    setStories([...stories, newStory]);

    // Method 2: Use ref method (preferred for dynamic updates)
    ref.current?.spliceStories([newStory]);
  };

  const addStoryToUser = () => {
    const newStoryItem = {
      id: `story${Date.now()}`,
      source: { uri: 'https://example.com/another-image.jpg' }
    };

    // Add to user1's stories
    ref.current?.spliceUserStories([newStoryItem], 'user1');
  };

  const replaceAllStories = () => {
    const completlyNew: InstagramStoriesProps['stories'] = [
      {
        id: 'user2',
        avatarSource: { uri: 'https://example.com/avatar2.jpg' },
        stories: [
          { id: 'story2', source: { uri: 'https://example.com/image2.jpg' } }
        ]
      }
    ];

    ref.current?.setStories(completlyNew);
  };

  return (
    <View style={{ flex: 1 }}>
      <InstagramStories ref={ref} stories={stories} />

      <Pressable onPress={addNewStories}>
        <Text>Add New User Stories</Text>
      </Pressable>

      <Pressable onPress={addStoryToUser}>
        <Text>Add Story to User 1</Text>
      </Pressable>

      <Pressable onPress={replaceAllStories}>
        <Text>Replace All Stories</Text>
      </Pressable>
    </View>
  );
};

export default DynamicStories;
```

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

### Advanced Instagram Stories Configuration

Source: https://github.com/birdwingo/react-native-instagram-stories/blob/main/_autodocs/usage-patterns.md

Provides a full-featured implementation with extensive configuration options, including custom headers, content rendering, and event handlers. Use this for a highly customized stories experience.

```typescript
import React, { useRef } from 'react';
import { View, Pressable, Text } from 'react-native';
import InstagramStories, {
  InstagramStoriesPublicMethods
} from '@birdwingo/react-native-instagram-stories';

const AdvancedStories = () => {
  const ref = useRef<InstagramStoriesPublicMethods>(null);

  const stories = [
    {
      id: 'user1',
      avatarSource: { uri: 'https://example.com/avatar1.jpg' },
      name: 'John Doe',
      renderStoryHeader: () => (
        <View style={{ flex: 1, justifyContent: 'center' }}>
          <Text style={{ color: 'white', fontWeight: 'bold' }}>Custom Header</Text>
        </View>
      ),
      stories: [
        {
          id: 'story1',
          source: { uri: 'https://example.com/image1.jpg' },
          renderContent: () => (
            <View style={{ position: 'absolute', bottom: 20, left: 20 }}>
              <Text style={{ color: 'white' }}>Story 1</Text>
            </View>
          )
        }
      ]
    }
  ];

  return (
    <View style={{ flex: 1 }}>
      <InstagramStories
        ref={ref}
        stories={stories}
        saveProgress={true}
        avatarSize={70}
        storyAvatarSize={30}
        showName={true}
        animationDuration={5000}
        videoAnimationMaxDuration={20000}
        hideElementsOnLongPress={true}
        loopingStories="all"
        backgroundColor="#1a1a1a"
        progressActiveColor="#4ECDC4"
        onSwipeUp={(userId, storyId) => {
          console.log(`Swiped up on ${userId}/${storyId}`);
        }}
        onStoryStart={(userId, storyId) => {
          console.log(`Story started: ${userId}/${storyId}`);
        }}
        onStoryEnd={(userId, storyId) => {
          console.log(`Story ended: ${userId}/${storyId}`);
        }}
      />

      <Pressable onPress={() => ref.current?.show()}>
        <Text>Show Stories</Text>
      </Pressable>
    </View>
  );
};

export default AdvancedStories;
```

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

### Configure Close Icon and Loader Colors

Source: https://github.com/birdwingo/react-native-instagram-stories/blob/main/_autodocs/configuration.md

Set custom colors for the close button and the loading spinner. Useful for matching your app's theme.

```typescript
<InstagramStories
  stories={stories}
  closeIconColor="#666666"
  loaderColor="#4ECDC4"
  loaderBackgroundColor="rgba(0,0,0,0.3)"
/>
```

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

### Custom Overlays and Footers

Source: https://github.com/birdwingo/react-native-instagram-stories/blob/main/_autodocs/usage-patterns.md

Add interactive elements like custom content overlays and call-to-action footers to stories. This is useful for e-commerce or promotional content.

```typescript
import React from 'react';
import {
  View,
  Text,
  Pressable,
  StyleSheet
} from 'react-native';
import InstagramStories from '@birdwingo/react-native-instagram-stories';

const OverlayStories = () => {
  const stories = [
    {
      id: 'user1',
      avatarSource: { uri: 'https://example.com/avatar1.jpg' },
      stories: [
        {
          id: 'story1',
          source: { uri: 'https://example.com/image1.jpg' },
          renderContent: () => (
            <View style={styles.overlay}>
              <Text style={styles.overlayText}>Limited Time Offer</Text>
              <Text style={styles.overlaySubText}>Save 50% Today</Text>
            </View>
          )
        }
      ]
    }
  ];

  const CustomFooter = () => (
    <View style={styles.footer}>
      <Pressable style={styles.ctaButton}>
        <Text style={styles.ctaText}>Shop Now</Text>
      </Pressable>
    </View>
  );

  return (
    <View style={{ flex: 1 }}>
      <InstagramStories
        stories={stories}
        footerComponent={<CustomFooter />}
        imageOverlayView={
          <View style={styles.globalOverlay}>
            <View style={styles.badge}>
              <Text style={styles.badgeText}>NEW</Text>
            </View>
          </View>
        }
      />
    </View>
  );
};

const styles = StyleSheet.create({
  overlay: {
    position: 'absolute',
    bottom: 60,
    left: 20,
    right: 20,
    backgroundColor: 'rgba(0,0,0,0.6)',
    padding: 16,
    borderRadius: 12
  },
  overlayText: {
    color: '#FFFFFF',
    fontSize: 20,
    fontWeight: 'bold',
    marginBottom: 4
  },
  overlaySubText: {
    color: '#E0E0E0',
    fontSize: 14
  },
  footer: {
    position: 'absolute',
    bottom: 0,
    left: 0,
    right: 0,
    padding: 16,
    backgroundColor: 'rgba(0,0,0,0.7)'
  },
  ctaButton: {
    backgroundColor: '#4ECDC4',
    paddingVertical: 12,
    paddingHorizontal: 32,
    borderRadius: 8,
    alignItems: 'center'
  },
  ctaText: {
    color: '#FFFFFF',
    fontSize: 16,
    fontWeight: '600'
  },
  globalOverlay: {
    ...StyleSheet.absoluteFillObject,
    justifyContent: 'flex-start',
    alignItems: 'flex-end',
    paddingTop: 20,
    paddingRight: 20
  },
  badge: {
    backgroundColor: '#FF6B6B',
    paddingHorizontal: 12,
    paddingVertical: 6,
    borderRadius: 20
  },
  badgeText: {
    color: '#FFFFFF',
    fontSize: 12,
    fontWeight: '700'
  }
});

export default OverlayStories;
```

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

### resume

Source: https://github.com/birdwingo/react-native-instagram-stories/blob/main/README.md

Resumes the paused story.

```APIDOC
## resume

### Description
Resumes the paused story.

### Method
`resume`

### Parameters
This method takes no parameters.

### Response
This method does not return a value.
```