Ngx Stories

An Angular component to render instagram like stories.

Screenshot

For Version 17+

Installation

Install the library via npm:

npm install ngx-stories

Usage

Import the NgxStoriesComponent in your component or module.

import { Component } from '@angular/core';
import { NgxStoriesComponent, StoryGroup } from 'ngx-stories';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [NgxStoriesComponent],
  templateUrl: './app.component.html',
  styleUrl: './app.component.css'
})
export class AppComponent {
  storyGroups: StoryGroup[] = [
    {
      name: 'John Doe',
      stories: [
        { type: 'image', content: 'https://example.com/story1.jpg' },
        { type: 'component', content: CustomComponent }, // pass any angular component
      ],
    },
    {
      name: 'Jane Smith',
      stories: [
        { type: 'video', content: 'https://example.com/video-story.mp4' },
      ],
    },
  ];
}

<ngx-stories [storyGroups]="storyGroups"></ngx-stories>

API Reference

Inputs

Property	Type	Required	Description
storyGroups	StoryGroup[]	Yes	An array of story groups to display.
options	NgxStoriesOptions	No	Configuration options for the stories.

Outputs

Event	Payload Type	Description
triggerOnEnd	void	Emitted when all stories in all groups have finished playing.
triggerOnExit	void	Emitted when the user triggers an exit action (e.g., swipe down).
triggerOnSwipeUp	void	Emitted when the user swipes up on a story.
onStoryGroupChange	number	Emitted when the story group changes. Payload is the new group index.
triggerOnStoryChange	StoryChangeEventData	Emitted when the individual story changes. see StoryChangeEventData interface below.

Interfaces

StoryGroup

interface StoryGroup {
  id?: string;      // Unique identifier (auto-assigned if missing)
  name: string;     // Name of the user/group displayed in the header
  stories: Story[]; // Array of stories for this group
}

Story

interface Story {
  id?: string;      // Unique identifier (auto-assigned if missing)
  type: 'image' | 'video' | 'component';
  content: string | Type<Component>; // URL for image/video, or Component class
}

NgxStoriesOptions

interface NgxStoriesOptions {
  width?: number;                 // Width of the story container (default: 338)
  height?: number;                // Height of the story container (default: 600)
  currentStoryIndex?: number;     // Start index for stories within a group (default: 0)
  currentStoryGroupIndex?: number;// Start index for story groups (default: 0)
  backlitColor?: string;         // Background color behind the story media (default: '#1b1b1b')
  enableGradientBackground?: boolean; // Enable Instagram-like gradient background (default: true)
}

StoryChangeEventData (Payload for triggerOnStoryChange)

interface StoryChangeEventData {
  currentStoryGroupName: string;
  currentStoryGroupIndex: number;
  currentStory: Story;
  currentStoryIndex: number;
  previousStory: Story | null;
  previousStoryIndex: number | null;
}

Features

Navigation & Gestures

• Swipe Left/Right: Navigate between stories and story groups (Mobile friendly).
• Swipe Down: Triggers the triggerOnExit event (typically used to close the story viewer).
• Swipe Up: Triggers the triggerOnSwipeUp event (can be used for "See More" links).
• Tap:
  • Right side: Go to next story.
  • Left side: Go to previous story.
• Hold: Pause the story. Release to resume.

Keyboard Support

• Arrow Right: Next story.
• Arrow Left: Previous story.
• Space: Toggle Pause/Play.
• Escape: triggers triggerOnExit.

Background Effects

• Gradient Background: Automatically extracts dominant colors from the image/video and creates a dynamic, smooth gradient background (similar to Instagram). This can be disabled via options.enableGradientBackground: false.
• Backlit Color: Fallback background color if gradient is disabled or color extraction fails.

Media Support

• Images: Preloading included.
• Videos: Auto-play, muted by default (toggle audio by clicking/tapping).
• Components: Render any Angular component as a story for maximum flexibility.

Other Features

• Progress Bar: Visual indicator of story duration and progress.
• Audio Control: Audio is muted by default. Tapping the screen un-mutes/mutes.
• Loading State: Animated SVG loader while content buffers.

Contributing

Contributing Guide

License

This library is licensed under the MIT License. Feel free to use and modify the code as per your needs.