# ramonszo/zuck.js

A javascript library that lets you add stories EVERYWHERE.

Repository: https://github.com/ramonszo/zuck.js
Canonical: https://ross.abutalabs.com/products/zuckjs
Homepage: https://ramon.codes/projects/zuck.js/
Language: TypeScript
License: MIT
License Family: permissive
Topics: stories, story, zuck, facebook, instagram, snapchat, whatsapp, slider, modal, viewer, media, react
Last push: 2025-04-16T22:40:43+00:00

## Health v2 (maintenance only)
Score: 39/100 (v2, computed 2026-09-03T02:20:16.233290+00:00)
- activity 16, release rhythm 35, longevity 100
- inputs: {"age_days": 3426, "days_push": 504, "days_rel": null, "gap_med": null, "n_releases_24m": 0}
- flags: no_releases
- formula: round(0.45*activity + 0.35*rhythm + 0.20*longevity); archived -> min(score, 10)

## Adoption (not part of the score)
Stars 3725, forks 311 (observed 2026-08-28T04:08:15.643124+00:00)

## What it is
A TypeScript JavaScript library that adds Snapchat/Instagram-style 'stories' timelines (photo/video story viewers with sliders, modals, and gestures) to any web page. It consumes story data from any endpoint such as JSON or Firebase and provides a simple API, custom CSS themes, a 3D cube effect, RTL support, and optional React integration.

## Use cases
- add instagram-style stories to my website
- implement a snapchat-like story viewer in javascript
- show a photo and video stories timeline on a web page
- build a whatsapp status style stories UI
- embed a facebook stories carousel in my web app
- use a stories viewer component with react
- create a tappable media slider with story progress bars

## When to choose
- You need ephemeral 'stories' UI (full-screen tap-through media viewer with progress bars) on a website or web app
- You want a framework-agnostic script with a simple add/update/remove API and optional React usage
- You need custom themes, gestures, RTL support, or story data loaded from any JSON/Firebase endpoint

## When to avoid
- You need a full social platform or feed product, not just the stories UI component
- You require server-side rendering without a DOM, since the library manipulates DOM elements directly
- You are building a native mobile app and need native story components rather than a browser-based script (mobile support has noted limitations)

## Facets
- artifact type: library
- maturity: active
- function: ui-components, animation
- domain: web-development, frontend, media, social-media
- platform: browser
- tags: stories-ui, instagram-stories, snapchat, facebook-stories, whatsapp-status, media-viewer, slider, modal, gestures, rtl-support, typescript, react, themes

## Member repositories
- ramonszo/zuck.js (main) score 39

## Provenance
- Observed fields: from GitHub, fetched 2026-08-28T04:08:15.643124+00:00.
- Health v2: computed from the inputs above; adoption is never an input.
- Inferred fields (summary, facets, guidance): AI-extracted, prompt v1, taxonomy v1, on 2026-08-29T18:29:16.402090+00:00, confidence not recorded.
  - readme: https://github.com/ramonszo/zuck.js (fetched 2026-08-28T04:08:15.643124+00:00, sha a61eb3a53ba9)
  - homepage: https://ramon.codes/projects/zuck.js/ (fetched 2026-08-29T09:24:16.389748+00:00, sha 9b3330c53403)
  - registry_npm: https://registry.npmjs.org/zuck.js (fetched 2026-08-29T09:24:16.398980+00:00, sha 559d72c42f6e)
- Data as of 2026-08-30T08:39:29.467469+00:00.