react-native-instagram-stories

To implement the stories component, import InstagramStories and provide a stories array. Each user object in the array requires an id, name, avatarSource, and a stories array containing individual story items.

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: 
  // if using typescript - useRef<InstagramStoriesPublicMethods>( null )
  const ref = useRef( null ); 

  const 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;

The InstagramStories component exposes several methods to programmatically control the stories player. You can access these via a ref.

Available Methods

• Story Management:

  • setStories(stories: InstagramStoryProps[]): Replace current stories with a new set.
  • spliceStories(stories: InstagramStoryProps[], index?: number): Insert new stories at a specific index (defaults to end).
  • spliceUserStories(stories: InstagramStoryProps[], user: string, index?: number): Insert new stories for a specific user.
  • clearProgressStorage(): Clear the progress storage for seen stories.

• Playback Control:

  • show(id?: string): Show the stories modal. If id is provided, starts at that story; otherwise, starts at the first.
  • hide(): Hide the stories if currently visible.
  • pause(): Pause the current story.
  • resume(): Resume the current story.
  • isPaused(): Returns true if the story is currently paused.
  • goToNextStory(): Go to the next story item.
  • goToPreviousStory(): Go to the previous story item.
  • goToSpecificStory(userId: string, index: number): Jump to a specific index for a user. If index doesn't exist, starts the first story.

• State Inspection:

  • getCurrentStory(): Returns { userId?: string, storyId?: string } for the currently playing story.

The InstagramStoryProps component (the main component of the library) accepts several props to customize the behavior and appearance of the stories.

Key Configuration Options

• Data: stories (required) is an array of InstagramStoryProps objects.
• Behavior:
  • saveProgress: Boolean to track and save seen stories.
  • loopingStories: Controls looping behavior. Options: 'none' (closes after last story), 'onlyLast' (loops only the last user), or 'all' (restarts from the beginning).
  • isVisible: Boolean to show the modal immediately on load.
  • hideElementsOnLongPress: Hides UI elements when the user long-presses to pause.
• Styling:
  • avatarSize: Size of the avatars in the list (default 60).
  • storyAvatarSize: Size of avatars in the story header (default 25).
  • backgroundColor: Background color of the container (default '#000000').
  • animationDuration: Duration of story animations in ms (default 10000).
• Callbacks:
  • onShow: Triggered when a story is shown.
  • onHide: Triggered when a story is hidden.
  • onSwipeUp: Triggered when a user swipes up on a story.
  • onStoryStart / onStoryEnd: Triggered at the start and end of a story lifecycle.

<InstagramStories
  stories={myStories}
  saveProgress={true}
  loopingStories="onlyLast"
  onStoryStart={(userId, storyId) => console.log(userId, storyId)}
/>

The following table lists the available props for the InstagramStories component.

The InstagramStories component is the main entry point for rendering an Instagram-style stories interface. It manages an avatar list and a modal for viewing stories. It supports progress saving, custom styling for avatars, and fine-grained control over story playback via a ref.

Key Props

• stories: An array of story data objects.
• saveProgress: Boolean indicating whether to persist story viewing progress in storage (default: false).
• isVisible: Boolean to control the visibility of the story modal.
• hideAvatarList: Boolean to hide the avatar list (default: false).
• avatarSize: Size of the avatars in the list.
• animationDuration: Duration for story transitions.
• videoProps: Configuration passed to the video player.
• videoAnimationMaxDuration: Maximum duration for video animations.
• backgroundColor: Background color of the story modal.
• closeIconColor: Color of the close icon in the modal.

import InstagramStories from '@birdwingo/react-native-instagram-stories';

// ... inside your component
<InstagramStories 
  stories={myStories} 
  saveProgress={true} 
  isVisible={true} 
/>