An Angular component to render instagram like stories.
Install the library via npm:
npm install ngx-storiesImport 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>| Property | Type | Required | Description |
|---|---|---|---|
storyGroups |
StoryGroup[] |
Yes | An array of story groups to display. |
options |
NgxStoriesOptions |
No | Configuration options for the stories. |
| 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 |
StoryChange |
Emitted when the individual story changes. see StoryChange interface below. |
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
}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
}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)
}interface StoryChange {
currentPerson: string;
currentPersonIndex: number;
currentStory: Story;
currentStoryIndex: number;
previousStory: Story | null;
previousStoryIndex: number | null;
}- Swipe Left/Right: Navigate between stories and story groups (Mobile friendly).
- Swipe Down: Triggers the
triggerOnExitevent (typically used to close the story viewer). - Swipe Up: Triggers the
triggerOnSwipeUpevent (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.
- Arrow Right: Next story.
- Arrow Left: Previous story.
- Space: Toggle Pause/Play.
- Escape: triggers
triggerOnExit.
- 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.
- 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.
- 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.
This library is licensed under the MIT License. Feel free to use and modify the code as per your needs.