{"id":29164991,"url":"https://github.com/oe/react-sticky-kit","last_synced_at":"2026-03-27T03:10:12.129Z","repository":{"id":293508561,"uuid":"984148707","full_name":"oe/react-sticky-kit","owner":"oe","description":"A lightweight, flexible React sticky container and item component library. Easily create sticky headers, sections, and advanced sticky layouts with support for multiple modes and edge cases.","archived":false,"fork":false,"pushed_at":"2025-06-08T09:07:38.000Z","size":268,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-03-01T08:39:31.522Z","etag":null,"topics":["react","react-sticky","sticky","sticky-header"],"latest_commit_sha":null,"homepage":"https://codesandbox.io/p/sandbox/dreamy-hofstadter-v9dzfz","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/oe.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-05-15T13:22:55.000Z","updated_at":"2025-06-08T09:07:33.000Z","dependencies_parsed_at":"2025-05-15T18:22:24.420Z","dependency_job_id":"6b188aa1-f4ae-4d6d-9912-42f2f1b53e0d","html_url":"https://github.com/oe/react-sticky-kit","commit_stats":null,"previous_names":["oe/react-sticky-kit"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/oe/react-sticky-kit","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oe%2Freact-sticky-kit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oe%2Freact-sticky-kit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oe%2Freact-sticky-kit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oe%2Freact-sticky-kit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/oe","download_url":"https://codeload.github.com/oe/react-sticky-kit/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oe%2Freact-sticky-kit/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31013961,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-27T02:58:54.984Z","status":"ssl_error","status_checked_at":"2026-03-27T02:58:46.993Z","response_time":164,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["react","react-sticky","sticky","sticky-header"],"created_at":"2025-07-01T07:08:48.526Z","updated_at":"2026-03-27T03:10:12.112Z","avatar_url":"https://github.com/oe.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# React Sticky Kit\n\n\u003cp align=\"left\"\u003e\n  \u003ca href=\"https://www.npmjs.com/package/react-sticky-kit\" target=\"_blank\"\u003e\n    \u003cimg src=\"https://img.shields.io/npm/v/react-sticky-kit.svg?style=flat-square\" alt=\"NPM Version\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://img.shields.io/npm/dm/react-sticky-kit?style=flat-square\" target=\"_blank\"\u003e\n    \u003cimg src=\"https://img.shields.io/npm/dm/react-sticky-kit?style=flat-square\" alt=\"NPM Downloads\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/oe/react-sticky-kit\" target=\"_blank\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/stars/oe/react-sticky-kit?style=flat-square\" alt=\"GitHub Stars\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/oe/react-sticky-kit/actions\" target=\"_blank\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/actions/workflow/status/oe/react-sticky-kit/ci.yml?style=flat-square\" alt=\"Build Status\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/oe/react-sticky-kit/blob/main/LICENSE\" target=\"_blank\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/license/oe/react-sticky-kit?style=flat-square\" alt=\"License\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://www.typescriptlang.org/\" target=\"_blank\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/TypeScript-5.0%2B-blue?logo=typescript\u0026style=flat-square\" alt=\"TypeScript\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"#ssr-ssg-support\" target=\"_blank\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/SSR%2FSSG-Compatible-brightgreen?style=flat-square\" alt=\"SSR/SSG Compatible\" /\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\nA lightweight, flexible React sticky container and item component library. Easily create sticky headers, sections, and advanced sticky layouts with support for multiple modes and edge cases.\n\n## Features\n\n- 📦 Simple API: `\u003cStickyContainer\u003e` and `\u003cStickyItem\u003e`\n- 🧩 Supports `replace`, `stack`, and `none` sticky modes\n- 🏷️ Customizable offset, z-index (baseZIndex), and sticky logic\n- 🖥️ Flexible reference containers (window, DOM elements, refs)\n- 🔄 Supports SSR/SSG (Next.js, Gatsby, Astro, etc.)\n- 🧪 Handles edge cases: empty sections, dynamic heights, zero-height headers, long headers, etc.\n- ⚡️ Written in TypeScript, fully typed\n- 🧪 Includes demo pages for real-world scenarios\n\n## Installation\n\n```bash\nnpm install react-sticky-kit\n# or\nyarn add react-sticky-kit\n# or\npnpm add react-sticky-kit\n```\n\n## Demo\n- [Apple iOS Contact App](https://codesandbox.io/p/sandbox/dreamy-hofstadter-v9dzfz)\n\n## Usage\n\n```tsx\nimport { StickyContainer, StickyItem } from 'react-sticky-kit';\n// !! Import styles for sticky components\nimport 'react-sticky-kit/dist/style.css';\n// or `import 'react-sticky-kit/style';` for more clean style path(require modern bundler tools)\n\nexport default function Example() {\n  return (\n    \u003cStickyContainer offsetTop={48} defaultMode=\"stack\" baseZIndex={300}\u003e\n      \u003cStickyItem\u003e\n        \u003cdiv\u003eSticky Header\u003c/div\u003e\n      \u003c/StickyItem\u003e\n      \u003cdiv\u003eContent...\u003c/div\u003e\n      \u003cStickyItem mode=\"replace\"\u003e\n        \u003cdiv\u003eAnother Sticky Header (replace mode)\u003c/div\u003e\n      \u003c/StickyItem\u003e\n      \u003cdiv\u003eMore Content...\u003c/div\u003e\n    \u003c/StickyContainer\u003e\n  );\n}\n```\n\n## Props\n\n### `\u003cStickyContainer /\u003e`\n| Prop                        | Type                                                 | Default     | Description                                                                                 |\n|-----------------------------|------------------------------------------------------|-------------|---------------------------------------------------------------------------------------------|\n| `offsetTop`                 | `number`                                             | `0`         | Offset from the top of the viewport                                                         |\n| `defaultMode`               | `'replace' \\| 'stack' \\| 'none'`                     | `'replace'` | Default sticky mode for all items                                                           |\n| `baseZIndex`                | `number`                                             | `200`       | Base z-index for sticky items. Should be greater than the number of sticky items.            |\n|                             |                                                      |             | In `replace` mode, z-index = baseZIndex - index; in `stack` mode, z-index = baseZIndex + index. |\n| `onStickyItemsHeightChange` | `(height: number) =\u003e void`                          |             | Callback when total sticky height changes                                                   |\n| `constraint`                | `'none'`                                             |             | Define the constraint for sticky behavior. 'none' = no constraints (CSS-like behavior) |\n\n### `\u003cStickyItem /\u003e`\n| Prop    | Type                                 | Default | Description                                 |\n|---------|--------------------------------------|---------|---------------------------------------------|\n| `mode`  | `'replace' \\| 'stack' \\| 'none'`     |         | Sticky mode for this item (overrides StickyContainer) |\n\n## Sticky Modes\n- **replace**: Only one sticky item is visible at a time, replacing the previous.\n- **stack**: Sticky items stack on top of each other.\n- **none**: Sticky is disabled for this item.\n\n## Constraint Behavior\n\nThe `constraint` prop allows you to control when sticky items should stop being sticky:\n\n```tsx\nimport React from 'react';\nimport { StickyContainer, StickyItem } from 'react-sticky-kit';\n\nfunction Example() {\n  return (\n    \u003cdiv\u003e\n      {/* 1. Default: Container-based constraint */}\n      \u003cStickyContainer\u003e\n        \u003cStickyItem\u003e\u003cdiv\u003eSticky stops when container leaves viewport\u003c/div\u003e\u003c/StickyItem\u003e\n        \u003cdiv\u003eContent...\u003c/div\u003e\n      \u003c/StickyContainer\u003e\n      \n      {/* 2. No constraints (like CSS position:sticky) */}\n      \u003cStickyContainer constraint=\"none\"\u003e\n        \u003cStickyItem\u003e\u003cdiv\u003eAlways sticky like CSS position:sticky\u003c/div\u003e\u003c/StickyItem\u003e\n        \u003cdiv\u003eContent...\u003c/div\u003e\n      \u003c/StickyContainer\u003e\n    \u003c/div\u003e\n  );\n}\n        \u003cdiv\u003eContent...\u003c/div\u003e\n      \u003c/StickyContainer\u003e\n    \u003c/div\u003e\n  );\n}\n```\n\n### Special behavior of `constraint=\"none\"`\n\nWhen you set `constraint=\"none\"`, the sticky items will always stick when they reach the top of the viewport, regardless of their parent container's visibility. This exactly matches the behavior of native CSS `position: sticky`.\n\nIn contrast, the default behavior (without specifying a constraint) only makes items sticky when their parent container is visible in the viewport.\n\n## Demo\n\nRun the demo locally:\n\n```bash\npnpm install\npnpm dev\n```\n\nOpen [http://localhost:5173](http://localhost:5173) and switch between demo pages to explore all features and edge cases:\n* [iOS Contact](http://localhost:5173/#ios-contact) a dead simple iOS contact clone\n* [Mixed mode](http://localhost:5173/#mixed-mode) mix replace/stack/none mode\n* [Nested](http://localhost:5173/#nested) nest sticky containers\n* [Dynamic sticky items](http://localhost:5173/#dynamic) dynamic sticky items(add/remove)\n* [Dynamic offsetTop](http://localhost:5173/#dynamic-offset) dynamic offsetTop that adapts to header height changes\n* [Constraint Demo](http://localhost:5173/#constraint) demo showing different constraint options\n\n## SSR/SSG Support\n\nReact Sticky Kit supports Server-Side Rendering (SSR) and Static Site Generation (SSG), working seamlessly with frameworks like Next.js, Gatsby, Astro, and more.\n\n### Next.js Example\n\n```tsx\n// pages/index.tsx\nimport { StickyContainer, StickyItem } from 'react-sticky-kit'\nimport 'react-sticky-kit/dist/style.css'\n\nexport default function Home() {\n  return (\n    \u003cStickyContainer\u003e\n      \u003cStickyItem\u003e\n        \u003cheader\u003eSticky Header\u003c/header\u003e\n      \u003c/StickyItem\u003e\n      \u003cmain\u003eContent...\u003c/main\u003e\n    \u003c/StickyContainer\u003e\n  )\n}\n```\n\n### Astro Example\n\n```astro\n---\n// src/pages/index.astro\nimport { StickyContainer, StickyItem } from 'react-sticky-kit'\nimport 'react-sticky-kit/dist/style.css'\n---\n\n\u003chtml\u003e\n  \u003chead\u003e...\u003c/head\u003e\n  \u003cbody\u003e\n    \u003cStickyContainer client:load\u003e\n      \u003cStickyItem\u003e\n        \u003cheader\u003eSticky Header\u003c/header\u003e\n      \u003c/StickyItem\u003e\n      \u003cdiv\u003eContent...\u003c/div\u003e\n    \u003c/StickyContainer\u003e\n  \u003c/body\u003e\n\u003c/html\u003e\n```\n\n## Publish steps\n\n`pnpm pub`\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foe%2Freact-sticky-kit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foe%2Freact-sticky-kit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foe%2Freact-sticky-kit/lists"}