{"id":39728271,"url":"https://github.com/dev-rajshekhar/rn-overlay-manager","last_synced_at":"2026-01-23T09:41:12.939Z","repository":{"id":332960168,"uuid":"1135692533","full_name":"dev-rajshekhar/rn-overlay-manager","owner":"dev-rajshekhar","description":"Overlay manager for React Native. Show modals, toasts, tooltips, and loaders from anywhere via a simple hook.","archived":false,"fork":false,"pushed_at":"2026-01-18T14:41:51.000Z","size":258,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-18T17:07:54.326Z","etag":null,"topics":["expo","react-native"],"latest_commit_sha":null,"homepage":"","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/dev-rajshekhar.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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-16T13:06:59.000Z","updated_at":"2026-01-18T14:41:55.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/dev-rajshekhar/rn-overlay-manager","commit_stats":null,"previous_names":["dev-rajshekhar/rn-overlay-manager"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/dev-rajshekhar/rn-overlay-manager","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dev-rajshekhar%2Frn-overlay-manager","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dev-rajshekhar%2Frn-overlay-manager/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dev-rajshekhar%2Frn-overlay-manager/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dev-rajshekhar%2Frn-overlay-manager/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dev-rajshekhar","download_url":"https://codeload.github.com/dev-rajshekhar/rn-overlay-manager/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dev-rajshekhar%2Frn-overlay-manager/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28686789,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-23T05:48:07.525Z","status":"ssl_error","status_checked_at":"2026-01-23T05:48:07.129Z","response_time":59,"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":["expo","react-native"],"created_at":"2026-01-18T10:57:40.226Z","updated_at":"2026-01-23T09:41:12.933Z","avatar_url":"https://github.com/dev-rajshekhar.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# rn-overlay-manager\n\n[![npm version](https://img.shields.io/npm/v/rn-overlay-manager.svg)](https://www.npmjs.com/package/rn-overlay-manager)\n[![npm downloads](https://img.shields.io/npm/dm/rn-overlay-manager.svg)](https://www.npmjs.com/package/rn-overlay-manager)\n\nOverlay manager for React Native. Show modals, toasts, tooltips, and loaders from anywhere via a simple hook.\n\n## Installation\n\n```sh\nnpm install rn-overlay-manager\n```\n\n```sh\nyarn add rn-overlay-manager\n```\n\nSafe-area support requires `react-native-safe-area-context`:\n\n```sh\nnpm install react-native-safe-area-context\n```\n\n## Setup\n\n```tsx\nimport { OverlayHost, OverlayProvider } from \"rn-overlay-manager\";\n\nexport default function App() {\n  return (\n    \u003cOverlayProvider tabBarHeight={0}\u003e\n      {/* app content */}\n      \u003cOverlayHost /\u003e\n    \u003c/OverlayProvider\u003e\n  );\n}\n```\n\n## Using with React Navigation\n\n```tsx\nimport {\n  NavigationContainer,\n  useNavigationContainerRef,\n} from \"@react-navigation/native\";\nimport {\n  NavigationOverlayProvider,\n  NavigationOverlayHost,\n} from \"rn-overlay-manager\";\n\nexport default function App() {\n  const navigationRef = useNavigationContainerRef();\n\n  return (\n    \u003cNavigationOverlayProvider navigationRef={navigationRef}\u003e\n      \u003cNavigationContainer ref={navigationRef}\u003e\n        \u003cRootNavigator /\u003e\n      \u003c/NavigationContainer\u003e\n      \u003cNavigationOverlayHost /\u003e\n    \u003c/NavigationOverlayProvider\u003e\n  );\n}\n```\n\nNotes:\n\n- Mount the host once near the root.\n- Overlays are global by default.\n- Use `scope: \"screen\"` to auto-clear overlays when the route changes (requires NavigationOverlayProvider).\n- `tabBarHeight` can be passed directly or updated via `useNavigationOverlayConfig`.\n\n## Usage\n\n## Demo\n\n![rn-overlay-manager](https://github.com/user-attachments/assets/c7c2c433-d330-4c57-adb7-9b7835f78a0a)\n\n### Toast\n\n```tsx\nconst overlay = useOverlay();\n\noverlay.toast({ message: \"Saved\", placement: \"bottom\" });\noverlay.toast({\n  message: \"Queued\",\n  queue: true,\n});\noverlay.toast({\n  message: \"Styled\",\n  backgroundColor: \"#2563EB\",\n  textStyle: { fontWeight: \"700\" },\n  toastStyle: { borderRadius: 12 },\n});\n```\n\n### Modal\n\n```tsx\noverlay.modal({\n  dismissible: true,\n  backdrop: \"dim\",\n  render: (api) =\u003e (\n    \u003cView\u003e\n      \u003cText\u003eConfirm?\u003c/Text\u003e\n      \u003cButton title=\"Close\" onPress={api.hide} /\u003e\n    \u003c/View\u003e\n  ),\n});\n```\n\n### Loader\n\n```tsx\nconst id = overlay.loader({ message: \"Loading...\" });\noverlay.hide(id);\n```\n\n### Tooltip\n\n```tsx\nconst anchorRef = React.useRef(null);\n\noverlay.tooltip({\n  anchorRef: anchorRef as unknown as TooltipAnchorRef,\n  text: \"Helpful tip\",\n  placement: \"auto\",\n});\n```\n\nTooltips clamp to the screen and safe-area bounds and auto-place above/below when `placement=\"auto\"`.\n\n### Custom overlays\n\n```tsx\nconst id = overlay.show({\n  type: \"custom\",\n  render: (api) =\u003e \u003cMyOverlay onClose={api.hide} /\u003e,\n  dismissible: true,\n  blockTouches: true,\n  backdrop: \"dim\",\n  priority: 10,\n});\n\noverlay.hide(id);\n```\n\n## API reference\n\n| Method             | Description                            | Returns |\n| ------------------ | -------------------------------------- | ------- |\n| `toast(options)`   | Show a toast notification.             | `id`    |\n| `modal(options)`   | Show a modal with a render override.   | `id`    |\n| `loader(options?)` | Show a blocking loader.                | `id`    |\n| `tooltip(options)` | Show a tooltip anchored to a ref.      | `id`    |\n| `show(options)`    | Show a custom overlay.                 | `id`    |\n| `hide(id)`         | Hide an overlay by id.                 | `void`  |\n| `hideAll(type?)`   | Hide all overlays, optionally by type. | `void`  |\n| `hideGroup(group)` | Hide all overlays in a group.          | `void`  |\n\n## Options by helper\n\n### toast(options)\n\n| Option            | Type                          | Default    | Notes                                |\n| ----------------- | ----------------------------- | ---------- | ------------------------------------ |\n| `message`         | `string`                      | required   | Text to display.                     |\n| `durationMs`      | `number`                      | `2000`     | Auto-dismiss delay.                  |\n| `placement`       | `\"top\" \\| \"bottom\"`           | `\"bottom\"` | Position within safe area.           |\n| `queue`           | `boolean`                     | `true`     | Queue when another toast is visible. |\n| `render`          | `(api, options) =\u003e ReactNode` | —          | Full custom renderer.                |\n| `toastStyle`      | `ViewStyle`                   | —          | Built-in toast container style.      |\n| `textStyle`       | `TextStyle`                   | —          | Built-in toast text style.           |\n| `backgroundColor` | `string`                      | —          | Built-in toast background.           |\n| `animation`       | `\"none\" \\| \"fade\" \\| \"scale\" \\| \"slide-up\" \\| \"slide-down\"` | `\"slide-up\"` | Enter/exit animation preset. |\n| `animationDurationMs` | `number`                  | `180`      | Animation duration in ms.            |\n| `animationEasing` | `\"default\" \\| \"linear\"`       | `\"default\"`| Animation easing preset.             |\n| `animatePresence` | `boolean`                     | `true`     | Keep mounted for exit animation.     |\n| `onShow`          | `() =\u003e void`                  | —          | Called when toast becomes visible.   |\n| `onHide`          | `() =\u003e void`                  | —          | Called when hide starts.             |\n| `onHidden`        | `() =\u003e void`                  | —          | Called after toast unmounts.         |\n\n### modal(options)\n\n| Option          | Type                            | Default      | Notes                               |\n| --------------- | ------------------------------- | ------------ | ----------------------------------- |\n| `render`        | `(api) =\u003e ReactNode`            | required     | Render modal content.               |\n| `dismissible`   | `boolean`                       | `true`       | Back button / backdrop dismissal.   |\n| `backdrop`      | `\"transparent\" \\| \"dim\"`        | `\"dim\"`      | Backdrop appearance.                |\n| `insets`        | `\"safeArea\" \\| \"none\" \\| {...}` | `\"safeArea\"` | Container padding strategy.         |\n| `avoidKeyboard` | `boolean`                       | `false`      | Shift upward when keyboard appears. |\n| `animation`     | `\"none\" \\| \"fade\" \\| \"scale\" \\| \"slide-up\" \\| \"slide-down\"` | `\"scale\"` | Enter/exit animation preset. |\n| `animationDurationMs` | `number`                   | `180`        | Animation duration in ms.           |\n| `animationEasing` | `\"default\" \\| \"linear\"`        | `\"default\"`  | Animation easing preset.            |\n| `animatePresence` | `boolean`                      | `true`       | Keep mounted for exit animation.    |\n| `onShow`        | `() =\u003e void`                    | —            | Called when modal becomes visible.  |\n| `onHide`        | `() =\u003e void`                    | —            | Called when hide starts.            |\n| `onHidden`      | `() =\u003e void`                    | —            | Called after modal unmounts.        |\n\n### loader(options)\n\n| Option             | Type                 | Default | Notes                  |\n| ------------------ | -------------------- | ------- | ---------------------- |\n| `message`          | `string`             | —       | Optional loading text. |\n| `render`           | `(api) =\u003e ReactNode` | —       | Full custom renderer.  |\n| `styles.container` | `ViewStyle`          | —       | Container override.    |\n| `styles.text`      | `TextStyle`          | —       | Text override.         |\n| `styles.spinner`   | `ViewStyle`          | —       | Spinner wrap override. |\n| `animation`        | `\"none\" \\| \"fade\" \\| \"scale\" \\| \"slide-up\" \\| \"slide-down\"` | `\"fade\"` | Enter/exit animation preset. |\n| `animationDurationMs` | `number`          | `180`    | Animation duration in ms. |\n| `animationEasing`  | `\"default\" \\| \"linear\"` | `\"default\"` | Animation easing preset. |\n| `animatePresence`  | `boolean`           | `true`   | Keep mounted for exit animation. |\n| `onShow`           | `() =\u003e void`        | —        | Called when loader becomes visible. |\n| `onHide`           | `() =\u003e void`        | —        | Called when hide starts. |\n| `onHidden`         | `() =\u003e void`        | —        | Called after loader unmounts. |\n\n### tooltip(options)\n\n| Option             | Type                                               | Default  | Notes                               |\n| ------------------ | -------------------------------------------------- | -------- | ----------------------------------- |\n| `anchorRef`        | `TooltipAnchorRef`                                 | required | Ref used for positioning.           |\n| `text`             | `string`                                           | —        | Built-in text.                      |\n| `placement`        | `\"auto\" \\| \"top\" \\| \"bottom\" \\| \"left\" \\| \"right\"` | `\"auto\"` | Auto picks top/bottom.              |\n| `type`             | `\"info\" \\| \"success\" \\| \"warning\" \\| \"error\"`      | `\"info\"` | Built-in color theme.               |\n| `dismissible`      | `boolean`                                          | `true`   | Outside press dismissal.            |\n| `autoDismissMs`    | `number`                                           | —        | Auto-dismiss timeout.               |\n| `styles.container` | `ViewStyle`                                        | —        | Container override.                 |\n| `styles.text`      | `TextStyle`                                        | —        | Text override.                      |\n| `render`           | `(api, options) =\u003e ReactNode`                      | —        | Full custom renderer.               |\n| `avoidKeyboard`    | `boolean`                                          | `false`  | Shift upward when keyboard appears. |\n| `animation`        | `\"none\" \\| \"fade\" \\| \"scale\" \\| \"slide-up\" \\| \"slide-down\"` | `\"fade\"` | Enter/exit animation preset. |\n| `animationDurationMs` | `number`                                      | `180`     | Animation duration in ms.           |\n| `animationEasing`  | `\"default\" \\| \"linear\"`                            | `\"default\"` | Animation easing preset.          |\n| `animatePresence`  | `boolean`                                          | `true`    | Keep mounted for exit animation.    |\n| `onShow`           | `() =\u003e void`                                       | —         | Called when tooltip becomes visible.|\n| `onHide`           | `() =\u003e void`                                       | —         | Called when hide starts.            |\n| `onHidden`         | `() =\u003e void`                                       | —         | Called after tooltip unmounts.      |\n\n### show(options)\n\n| Option          | Type                               | Notes                               |\n| --------------- | ---------------------------------- | ----------------------------------- |\n| `type`          | `OverlayType`                      | Used by `hideAll(type)`.            |\n| `group`         | `string`                           | Used by `hideGroup(group)`.         |\n| `render`        | `(api, props) =\u003e ReactNode`        | Custom overlay renderer.            |\n| `dismissible`   | `boolean`                          | Back button / backdrop dismissal.   |\n| `blockTouches`  | `boolean`                          | Whether touches pass through.       |\n| `backdrop`      | `\"none\" \\| \"transparent\" \\| \"dim\"` | Backdrop appearance.                |\n| `priority`      | `number`                           | Higher value renders above lower.   |\n| `insets`        | `\"safeArea\" \\| \"none\" \\| {...}`    | Insets strategy.                    |\n| `avoidKeyboard` | `boolean`                          | Shift upward when keyboard appears. |\n| `animation`     | `\"none\" \\| \"fade\" \\| \"scale\" \\| \"slide-up\" \\| \"slide-down\"` | Enter/exit animation preset. |\n| `animationDurationMs` | `number`                    | Duration in ms.                     |\n| `animationEasing` | `\"default\" \\| \"linear\"`          | Easing preset.                      |\n| `animatePresence` | `boolean`                        | Keep mounted for exit animation.    |\n| `onShow`        | `() =\u003e void`                      | Called when overlay becomes visible.|\n| `onHide`        | `() =\u003e void`                      | Called when hide starts.            |\n| `onHidden`      | `() =\u003e void`                      | Called after overlay unmounts.      |\n\n### OverlayProvider props\n\n| Prop           | Type     | Default | Notes                               |\n| -------------- | -------- | ------- | ----------------------------------- |\n| `tabBarHeight` | `number` | `0`     | Used by `insets=\"safeArea+tabBar\"`. |\n\n## Example app\n\n```sh\ncd example \u0026\u0026 npm i \u0026\u0026 npx expo start\n```\n\n## Troubleshooting\n\n- Safe-area support requires `react-native-safe-area-context`.\n- Mount `\u003cOverlayHost /\u003e` once near the root.\n- Tooltips require a valid `anchorRef` (must be measurable).\n\n## Safe-area note\n\nInsets read from `react-native-safe-area-context` when available. If it is not installed or not provided, insets default to zero. Use `tabBarHeight` when using `insets=\"safeArea+tabBar\"`.\n\n## Keyboard avoidance\n\n`avoidKeyboard` provides a minimal upward shift when the keyboard is visible. It is not a full scroll-to-input solution.\n\n## Animations\n\nAll overlays can opt in to enter/exit animations via `animation`, `animationDurationMs`, and `animationEasing`. Built-in defaults:\n\n- modal: `scale`\n- toast: `slide-up`\n- tooltip: `fade`\n- loader: `fade`\n\n## Lifecycle callbacks\n\nUse `onShow`, `onHide`, and `onHidden` on any overlay (including built-ins) to react to appearance and dismissal. `onHidden` fires after exit animation completes (or immediately if animations are disabled).\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdev-rajshekhar%2Frn-overlay-manager","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdev-rajshekhar%2Frn-overlay-manager","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdev-rajshekhar%2Frn-overlay-manager/lists"}