{"id":13601933,"url":"https://github.com/gorhom/react-native-portal","last_synced_at":"2025-05-15T05:08:08.635Z","repository":{"id":37467712,"uuid":"319764340","full_name":"gorhom/react-native-portal","owner":"gorhom","description":"A simplified portal implementation for ⭕️ React Native \u0026 Web ⭕️.","archived":false,"fork":false,"pushed_at":"2023-06-28T20:02:34.000Z","size":680,"stargazers_count":702,"open_issues_count":30,"forks_count":41,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-04-14T08:12:09.578Z","etag":null,"topics":["portal","react","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/gorhom.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null},"funding":{"github":"gorhom"}},"created_at":"2020-12-08T21:23:01.000Z","updated_at":"2025-04-13T03:37:58.000Z","dependencies_parsed_at":"2022-07-12T14:50:49.363Z","dependency_job_id":null,"html_url":"https://github.com/gorhom/react-native-portal","commit_stats":{"total_commits":55,"total_committers":6,"mean_commits":9.166666666666666,"dds":0.2909090909090909,"last_synced_commit":"b1fe33bbe1d6c26acb31df51d67b09c68a3d5121"},"previous_names":[],"tags_count":19,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gorhom%2Freact-native-portal","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gorhom%2Freact-native-portal/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gorhom%2Freact-native-portal/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gorhom%2Freact-native-portal/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gorhom","download_url":"https://codeload.github.com/gorhom/react-native-portal/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254276447,"owners_count":22043867,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["portal","react","react-native"],"created_at":"2024-08-01T18:01:10.268Z","updated_at":"2025-05-15T05:08:03.625Z","avatar_url":"https://github.com/gorhom.png","language":"TypeScript","funding_links":["https://github.com/sponsors/gorhom"],"categories":["TypeScript"],"sub_categories":[],"readme":"# React Native Portal\n\n[![React Native Portal](https://img.shields.io/npm/v/@gorhom/portal?style=flat-square)](https://www.npmjs.com/package/@gorhom/portal) [![npm](https://img.shields.io/npm/l/@gorhom/portal?style=flat-square)](https://www.npmjs.com/package/@gorhom/portal) [![npm](https://img.shields.io/badge/types-included-blue?style=flat-square)](https://www.npmjs.com/package/@gorhom/portal) [![runs with expo](https://img.shields.io/badge/Runs%20with%20Expo-4630EB.svg?style=flat-square\u0026logo=EXPO\u0026labelColor=f3f3f3\u0026logoColor=000)](https://snack.expo.io/@gorhom/portal-example)\n\nA simplified portal implementation for ⭕️ React Native ⭕️.\n\n![React Native Portal](./preview.jpg)\n\n---\n\n## Features\n\n- Multi portals handling.\n- Multi portal hosts handling.\n- Allow override functionality.\n- Compatible with `React Native Web`.\n- Compatible with `Expo`, [check out the project Expo Snack](https://snack.expo.io/@gorhom/portal-example).\n- Written in `TypeScript`.\n\n## Installation\n\n```sh\nyarn add @gorhom/portal\n```\n\n## Usage\n\n### Simple Portal\n\nThis is the very simple usage of this library, where you will teleport your content to the `PortalProvider` layer of the app.\n\nFirst, you will need to add `PortalProvider` to your root component - this usually be the `App.tsx`.\n\n```tsx\nexport const App = () =\u003e (\n  \u003cPortalProvider\u003e\n  {... your app goes here}\n  \u003c/PortalProvider\u003e\n);\n```\n\nLast, you wrap the content that you want to teleport with `Portal`.\n\n```tsx\nconst BasicScreen = () =\u003e {\n  return (\n    { ... }\n    \u003cPortal\u003e\n      \u003cText\u003e\n        Text to be teleported to the root host\n      \u003c/Text\u003e\n    \u003c/Portal\u003e\n    { ... }\n  );\n};\n```\n\n### Custom Portal Host\n\nThis is when you need to teleport your content to a custom portal host `PortalHost` at any layer in the app.\n\nFirst, you will need to add `PortalProvider` to your root component - this usually be the `App.tsx`.\n\n```tsx\nexport const App = () =\u003e (\n  \u003cPortalProvider\u003e\n  {... your app goes here ...}\n  \u003c/PortalProvider\u003e\n);\n```\n\nSecond, you will need to add `PortalHost` at any layer in your app, with a custom name.\n\n```tsx\nconst CustomView = () =\u003e {\n  return (\n    { ... }\n    \u003cPortalHost name=\"CustomPortalHost\" /\u003e\n    { ... }\n  );\n};\n```\n\nLast, you wrap the content that you want to teleport with `Portal` and the custom portal host name.\n\n```tsx\nconst BasicScreen = () =\u003e {\n  return (\n    { ... }\n    \u003cPortal hostName=\"CustomPortalHost\"\u003e\n      \u003cText\u003e\n        Text to be teleported to the CustomView component\n      \u003c/Text\u003e\n    \u003c/Portal\u003e\n    { ... }\n  );\n};\n```\n\n### React Native Screens integration\n\nIn order to get your teleported content on top of all native views, you will need to wrap your content with `FullWindowOverlay` from `react-native-screens`.\n\n```tsx\nimport { FullWindowOverlay } from 'react-native-screens';\n\nconst BasicScreen = () =\u003e {\n  return (\n    { ... }\n    \u003cPortal\u003e\n      \u003cFullWindowOverlay style={StyleSheet.absoluteFill}\u003e\n        \u003cText\u003e\n          Text to be teleported to the CustomView component\n        \u003c/Text\u003e\n      \u003c/FullWindowOverlay\u003e\n    \u003c/Portal\u003e\n    { ... }\n  );\n};\n```\n### React Native Gesture Handler\n\nTo avoid issues when using the React Native Portal with React Native Gesture Handler, you must place the `PortalProvider` under the `GestureHandlerRootView`, otherwise it might freeze your app.\n\n```tsx\nexport const App = () =\u003e (\n  \u003cGestureHandlerRootView\u003e\n    \u003cPortalProvider\u003e\n    {... your app goes here}\n    \u003c/PortalProvider\u003e\n  \u003c/GestureHandlerRootView\u003e\n);\n```\n\n\u003e Read more about the [app freezing issue](https://github.com/gorhom/react-native-portal/issues/24).\n\n## Props\n\n### Portal Props\n\n#### `name`\n\nPortal's key or name to be used as an identifer.\n\n\u003e `required:` NO | `type:` string | `default:` auto generated unique key\n\n#### `hostName`\n\nHost's key or name to teleport the portal content to.\n\n\u003e `required:` NO | `type:` string | `default:` 'root'\n\n#### `handleOnMount`\n\nOverride internal mounting functionality, this is useful if you want to trigger any action before mounting the portal content.\n\n```ts\ntype handleOnMount = (mount?: () =\u003e void) =\u003e void;\n```\n\n\u003e `required:` NO | `type:` function | `default:` undefined\n\n#### `handleOnUnmount`\n\nOverride internal un-mounting functionality, this is useful if you want to trigger any action before un-mounting the portal content.\n\n```ts\ntype handleOnUnmount = (unmount?: () =\u003e void) =\u003e void;\n```\n\n\u003e `required:` NO | `type:` function | `default:` undefined\n\n#### `children`\n\nPortal's content.\n\n\u003e `required:` NO | `type:` ReactNode | ReactNode[] | `default:` undefined\n\n### PortalHost Props\n\n#### `name`\n\nHost's key or name to be used as an identifier.\n\n\u003e `required:` YES | `type:` string\n\n## Hooks\n\n### `usePortal`\n\nTo access internal functionalities of all portals.\n\n```ts\n/**\n * @param hostName host name or key.\n */\ntype usePortal = (hostName: string = 'root') =\u003e {\n  /**\n   * Register a new host.\n   */\n  registerHost: () =\u003e void;\n  /**\n   * Deregister a host.\n   */\n  deregisterHost: () =\u003e void;\n  /**\n   * Add portal to the host container.\n   * @param name portal name or key\n   * @param node portal content\n   */\n  addPortal: (name: string, node: ReactNode) =\u003e void;\n  /**\n   * Update portal content.\n   * @param name portal name or key\n   * @param node portal content\n   */\n  updatePortal: (name: string, node: ReactNode) =\u003e void;\n  /**\n   * Remove portal from host container.\n   * @param name portal name or key\n   */\n  removePortal: (name: string) =\u003e void;\n};\n```\n\n\u003ch2 id=\"built-with\"\u003eBuilt With ❤️\u003c/h2\u003e\n\n- [@react-native-community/bob](https://github.com/react-native-community/bob)\n\n## Author\n\n- [Mo Gorhom](https://gorhom.dev/)\n\n## Sponsor \u0026 Support\n\nTo keep this library maintained and up-to-date please consider [sponsoring it on GitHub](https://github.com/sponsors/gorhom). Or if you are looking for a private support or help in customizing the experience, then reach out to me on Twitter [@gorhom](https://twitter.com/gorhom).\n\n## License\n\n[MIT](./LICENSE)\n\n---\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://gorhom.dev/#gh-light-mode-only\" target=\"_blank\"\u003e\n    \u003cimg height=\"18\" alt=\"Mo Gorhom\" src=\"./mogorhom-light.png\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://gorhom.dev/#gh-dark-mode-only\" target=\"_blank\"\u003e\n    \u003cimg height=\"18\" alt=\"Mo Gorhom\" src=\"./mogorhom-dark.png\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgorhom%2Freact-native-portal","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgorhom%2Freact-native-portal","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgorhom%2Freact-native-portal/lists"}