react-native-awesome-stories v0.2.1-4

react-native-awesome-stories

A fast and optimized library for rendering stories with smooth animations and gestures. Supports story lists and an integrated player with full customization.

Installation

npm install react-native-awesome-stories

yarn add react-native-awesome-stories

Peer Dependencies

This library requires the following peer dependencies to be installed in your project:

{
  "react-native-gesture-handler": ">=2.10.0",
  "react-native-reanimated": ">=3.10.0",
  "react-native-svg": "*"
}

Basic Usage

First, wrap your app with StoriesProvider and GestureHandlerRootView:

// App.tsx
import { GestureHandlerRootView } from 'react-native-gesture-handler';
import { StoriesProvider } from 'react-native-awesome-stories';

export default function App() {
  return (
    <GestureHandlerRootView style={{ flex: 1 }}>
      <StoriesProvider
        theme={{
          viewedBorderColor: 'gray',
          listItemStyle: {
            borderRadius: 12,
            borderWidth: 3,
            width: 80,
            height: 80,
            borderColor: 'yellow',
          },
        }}
      >
        <YourApp />
      </StoriesProvider>
    </GestureHandlerRootView>
  );
}

Then use StoriesList component to display stories:

// Stories.tsx
import { SafeAreaView } from 'react-native';
import { StoriesList } from 'react-native-awesome-stories';

const stories = [
  {
    id: '1',
    image: 'https://example.com/preview1.jpg',
    title: 'Story 1',
    isViewed: false,
    steps: [
      {
        id: '1-1',
        image: 'https://example.com/story1-1.jpg',
        title: 'Step 1',
        duration: 5000
      },
      {
        id: '1-2',
        image: 'https://example.com/story1-2.jpg',
        title: 'Step 2',
        duration: 3000
      }
    ]
  },
  // ... more stories
];

export function Stories() {
  return (
    <SafeAreaView style={{ flex: 1 }}>
      <StoriesList
        stories={stories}
        config={{
          renderContent: () => null,
          onStoryStepIndexChange: ({ storyIndex, stepIndex }) => {
            console.log('Current position:', storyIndex, stepIndex);
          },
        }}
        onStoryPress={async (story) => {
          // Handle story press, e.g. load data
          await new Promise(resolve => setTimeout(resolve, 1000));
        }}
        flatListProps={{
          onEndReached: () => {
            // Load more stories
          },
        }}
      />
    </SafeAreaView>
  );
}

StoriesProvider

The StoriesProvider component allows you to customize the appearance of the stories list in your application using a theme configuration.

Usage

Wrap your application with StoriesProvider and provide a custom theme if needed:

<StoriesProvider theme={customTheme}>
  <YourApp />
</StoriesProvider>

Props

Theme Configuration Type

export type StoriesThemeConfigType = {
  borderColor?: string;
  viewedBorderColor?: string;
  listItemStyle?: Omit<ViewStyle, 'width' | 'height' | 'borderRadius'> & {
    width: number;
    height: number;
    borderRadius?: number;
  };
  skeletonBg?: string;
  skeletonTintColor?: string;
};

Story List Data Type

The library provides a structured way to define story list items and their steps using the following types:

export type StoryListItemType<T = {}> = {
  id: string;
  image: string;
  title: string;
  isViewed?: boolean;
  steps: StoryStepType<T>[];
};

export type StoryStepType<T = {}> = {
  id: string;
  image: string;
  title: string;
  duration?: number;
} & T;

Description of StoryListItemType

Description of StoryStepType

This type system allows you to manage and extend story data flexibly, making it easy to integrate into different use cases. This allows for full customization of the story list's appearance, ensuring a seamless integration with your app's design.

StoriesList Props

Image prefetch example

const stories = [
  // your stories
];

<StoriesList
  stories={stories}
  onStoryPress={async (item) => {
    const promises = item.steps.map((step) => new Promise(async (resolve) => {
      await Image.prefetch(step.image);
      resolve(true);
    }));
    await Promise.all(promises);
  }}
/>

StoriesConfigType<T> Type

useStoriesController Hook

The useStoriesController hook provides access to the StoriesControllerContext, allowing you to control the story player, including opening and closing it, and tracking its state.

Usage Example

import { useStoriesController } from 'react-native-awesome-stories';

const MyComponent = () => {
  const { openPlayer, closePlayer, isPlayerOpened } = useStoriesController();

  const openStoryPlayer = () => {
    openPlayer({
      stories: myStories,       // Optional, pass the stories array. Will use the passed StoriesList stories if  not specified
      storyIndex: 0,            // Optional story index
      stepIndex: 0,             // Optional step index
      config: myPlayerConfig,   // Optional player configuration
    });
  };

  const closeStoryPlayer = () => {
    closePlayer();
  };

  return (
    <>
      <Button onPress={openStoryPlayer}>Open Story Player</Button>
      <Button onClick={closeStoryPlayer}>Close Story Player</Button>
    </>
  );
};

Contributing

See the contributing guide to learn how to contribute to the repository and the development workflow.

License

MIT