{"id":19251040,"url":"https://github.com/onesignal/react-onesignal","last_synced_at":"2026-02-27T18:55:52.700Z","repository":{"id":39025537,"uuid":"246692123","full_name":"OneSignal/react-onesignal","owner":"OneSignal","description":"React OneSignal Module: Make it easy to integrate OneSignal with your React App!","archived":false,"fork":false,"pushed_at":"2025-05-13T19:02:23.000Z","size":849,"stargazers_count":79,"open_issues_count":13,"forks_count":30,"subscribers_count":30,"default_branch":"main","last_synced_at":"2025-05-16T00:18:33.149Z","etag":null,"topics":["email","in-app-messaging","notifications","push-notifications","react","sms","typescript"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/OneSignal.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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}},"created_at":"2020-03-11T22:26:11.000Z","updated_at":"2025-05-13T19:02:27.000Z","dependencies_parsed_at":"2024-11-09T18:21:45.283Z","dependency_job_id":"1d6ccc09-8251-48e6-bbd3-fb5b02e7b2c1","html_url":"https://github.com/OneSignal/react-onesignal","commit_stats":{"total_commits":129,"total_committers":14,"mean_commits":9.214285714285714,"dds":0.5503875968992248,"last_synced_commit":"7599fb5062b54604c19574cf92b3c6830972eba4"},"previous_names":[],"tags_count":25,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OneSignal%2Freact-onesignal","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OneSignal%2Freact-onesignal/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OneSignal%2Freact-onesignal/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OneSignal%2Freact-onesignal/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/OneSignal","download_url":"https://codeload.github.com/OneSignal/react-onesignal/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254493378,"owners_count":22080126,"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":["email","in-app-messaging","notifications","push-notifications","react","sms","typescript"],"created_at":"2024-11-09T18:19:43.359Z","updated_at":"2026-02-27T18:55:52.679Z","avatar_url":"https://github.com/OneSignal.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003eWelcome to react-onesignal 👋\u003c/h1\u003e\n\u003cp\u003e\n  \u003ca href=\"https://www.npmjs.com/package/react-onesignal\" target=\"_blank\"\u003e\n    \u003cimg alt=\"Version\" src=\"https://img.shields.io/npm/v/react-onesignal.svg\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/OneSignal/react-onesignal#readme\" target=\"_blank\"\u003e\n    \u003cimg alt=\"Documentation\" src=\"https://img.shields.io/badge/documentation-yes-brightgreen.svg\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/OneSignal/react-onesignal/graphs/commit-activity\" target=\"_blank\"\u003e\n    \u003cimg alt=\"Maintenance\" src=\"https://img.shields.io/badge/Maintained%3F-yes-green.svg\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://twitter.com/onesignal\" target=\"_blank\"\u003e\n    \u003cimg alt=\"Twitter: onesignal\" src=\"https://img.shields.io/twitter/follow/onesignal.svg?style=social\" /\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n\u003e This is a JavaScript module that can be used to easily include [OneSignal](https://onesignal.com/) code in a website or app in practically any JS front-end codebase (not limited to React).\n\n- 🏠 [Homepage](https://github.com/OneSignal/react-onesignal#readme)\n- 🖤 [npm](https://www.npmjs.com/package/react-onesignal)\n\nOneSignal is the world's leader for Mobile Push Notifications, Web Push, and In-App Messaging. It is trusted by 2 million+ developers to send 12 billion Push Notifications per day.\n\nYou can find more information on OneSignal [here](https://onesignal.com/).\n\n### Migration Guides\n\nVersion 3.0 was recently released and includes breaking changes. See the [Migration Guide](https://github.com/OneSignal/react-onesignal/blob/main/MigrationGuide.md) to update your implementation.\n\n## Contents\n\n- [Install](#install)\n- [Usage](#usage)\n- [API](#onesignal-api)\n- [Advanced Usage](#advanced-usage)\n\n---\n\n## Install\n\n### npm\n\n```bash\nnpm install --save react-onesignal\n```\n\n### yarn\n\n```bash\nyarn add react-onesignal\n```\n\n---\n\n## Usage\n\nInitialize OneSignal with your `appId` via the `options` parameter:\n\n```js\nimport OneSignal from 'react-onesignal';\n\nOneSignal.init({ appId: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' });\n```\n\nThe `init` function returns a promise that resolves when OneSignal is loaded.\n\n**Examples**\n\n```js\nawait OneSignal.init({ appId: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' });\n// do other stuff\n```\n\n---\n\n```js\nconst [initialized, setInitialized] = useState(false);\nOneSignal.init({ appId: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' }).then(() =\u003e {\n  setInitialized(true);\n  OneSignal.Slidedown.promptPush();\n  // do other stuff\n});\n```\n\n### Init Options\n\nYou can pass other [options](https://documentation.onesignal.com/docs/web-sdk-reference#init) to the `init` function. Use these options to configure personalized prompt options, auto-resubscribe, and more.\n\n\u003cdetails\u003e\n  \u003csummary\u003eExpand to see more options\u003c/summary\u003e\n\n| Property Name                    | Type                 | Description                                              |\n| -------------------------------- | -------------------- | -------------------------------------------------------- |\n| `appId`                          | `string`             | The ID of your OneSignal app.                            |\n| `autoRegister`                   | `boolean` (optional) | Whether or not to automatically register the user.       |\n| `autoResubscribe`                | `boolean` (optional) | Whether or not to automatically resubscribe the user.    |\n| `path`                           | `string` (optional)  | The path to the OneSignal service worker file.           |\n| `serviceWorkerPath`              | `string` (optional)  | The path to the OneSignal service worker script.         |\n| `serviceWorkerUpdaterPath`       | `string` (optional)  | The path to the OneSignal service worker updater script. |\n| `subdomainName`                  | `string` (optional)  | The subdomain of your OneSignal app.                     |\n| `allowLocalhostAsSecureOrigin`   | `boolean` (optional) | Whether or not to allow localhost as a secure origin.    |\n| `requiresUserPrivacyConsent`     | `boolean` (optional) | Whether or not the user's consent is required.           |\n| `persistNotification`            | `boolean` (optional) | Whether or not notifications should persist.             |\n| `notificationClickHandlerMatch`  | `string` (optional)  | The URL match pattern for notification clicks.           |\n| `notificationClickHandlerAction` | `string` (optional)  | The action to perform when a notification is clicked.    |\n| `welcomeNotification`            | `object` (optional)  | The welcome notification configuration.                  |\n| `notifyButton`                   | `object` (optional)  | The notify button configuration.                         |\n| `promptOptions`                  | `object` (optional)  | Additional options for the subscription prompt.          |\n| `webhooks`                       | `object` (optional)  | The webhook configuration.                               |\n| `[key: string]`                  | `any`                | Additional properties can be added as needed.            |\n\n**Service Worker Params**\nYou can customize the location and filenames of service worker assets. You are also able to specify the specific scope that your service worker should control. You can read more [here](https://documentation.onesignal.com/docs/onesignal-service-worker#custom-code-setup).\n\nIn this distribution, you can specify the parameters via the following:\n\n| Field                | Details                                                                                                              |\n| -------------------- | -------------------------------------------------------------------------------------------------------------------- |\n| `serviceWorkerParam` | Use to specify the scope, or the path the service worker has control of. Example: `{ scope: \"/js/push/onesignal/\" }` |\n| `serviceWorkerPath`  | The path to the service worker file.                                                                                 |\n\n\u003c/details\u003e\n\n---\n\n### Service Worker File\n\nIf you haven't done so already, you will need to add the [OneSignal Service Worker file](https://github.com/OneSignal/OneSignal-Website-SDK/files/11480764/OneSignalSDK-v16-ServiceWorker.zip) to your site ([learn more](https://documentation.onesignal.com/docs/onesignal-service-worker#upload-the-js-file-to-your-server)).\n\nThe OneSignal SDK file must be publicly accessible. You can put them in your top-level root or a subdirectory. However, if you are placing the file not on top-level root make sure to specify the path via the service worker params in the init options (see section above).\n\n**Tip:**\nVisit `https://yoursite.com/OneSignalSDKWorker.js` in the address bar to make sure the files are being served successfully.\n\n---\n\n### Typescript\n\nThis package includes Typescript support.\n\n```ts\ninterface IOneSignalOneSignal {\n  Slidedown: IOneSignalSlidedown;\n  Notifications: IOneSignalNotifications;\n  Session: IOneSignalSession;\n  User: IOneSignalUser;\n  Debug: IOneSignalDebug;\n  login(externalId: string, jwtToken?: string): Promise\u003cvoid\u003e;\n  logout(): Promise\u003cvoid\u003e;\n  init(options: IInitObject): Promise\u003cvoid\u003e;\n  setConsentGiven(consent: boolean): Promise\u003cvoid\u003e;\n  setConsentRequired(requiresConsent: boolean): Promise\u003cvoid\u003e;\n}\n```\n\n### OneSignal API\n\nSee the official [OneSignal WebSDK reference](https://documentation.onesignal.com/docs/web-sdk-reference) for information on all available SDK functions.\n\n---\n\n## Advanced Usage\n\n### Events and Event Listeners\n\nUse listeners to react to OneSignal-related events:\n\n### Notifications Namespace\n\n| Event Name                | Callback Argument Type                 |\n| ------------------------- | -------------------------------------- |\n| 'click'                   | NotificationClickEvent                 |\n| 'foregroundWillDisplay'   | NotificationForegroundWillDisplayEvent |\n| 'dismiss'                 | NotificationDismissEvent               |\n| 'permissionChange'        | boolean                                |\n| 'permissionPromptDisplay' | void                                   |\n\n### Slidedown Namespace\n\n| Event Name       | Callback Argument Type |\n| ---------------- | ---------------------- |\n| 'slidedownShown' | boolean                |\n\n### Push Subscription Namespace\n\n| Event Name | Callback Argument Type |\n| ---------- | ---------------------- |\n| 'change'   | boolean                |\n\n**Example**\n\n```js\nOneSignal.Notifications.addEventListener('click', (event) =\u003e {\n  console.log('The notification was clicked!', event);\n});\n```\n\nSee the [OneSignal WebSDK Reference](https://documentation.onesignal.com/docs/web-sdk-reference#addeventlistener-notifications) for all available event listeners.\n\n## Troubleshooting\n\n### `window.OneSignal already defined as 'object'!`\n\nYou will get this error if you initialize twice. Make sure you are only initializing one time. When wrapped with `React.StrictMode`, your app might be rendering twice.\n\n## Example App\n\nThis repo includes an `example` React application implementing OneSignal. It was created using `create-react-app`. The app uses this repository's root level directory as the `react-onesignal` package and will bundle any changes on every run.\n\n---\n\n## 🤝 Contributing\n\nContributions, issues and feature requests are welcome!\u003cbr /\u003eFeel free to check [issues page](https://github.com/OneSignal/react-onesignal/issues).\n\n## Show your support\n\nGive a ⭐️ if this project helped you!\n\n## OneSignal\n\n- [Website](https://onesignal.com)\n- Twitter: [@onesignal](https://twitter.com/onesignal)\n- Github: [@OneSignal](https://github.com/OneSignal)\n- LinkedIn: [@onesignal](https://linkedin.com/company/onesignal)\n\n## Discord\n\nReach out to us via our [Discord server](https://discord.com/invite/EP7gf6Uz7G)!\n\n## 📝 License\n\nCopyright © 2023 [OneSignal](https://github.com/OneSignal).\u003cbr /\u003e\nThis project is [Modified MIT](https://github.com/OneSignal/react-onesignal/blob/master/LICENSE) licensed.\n\n## Thanks\n\nSpecial thanks to [pedro-lb](https://github.com/pedro-lb) and others for work on the project this package is [based on](https://github.com/pedro-lb/react-onesignal).\n\u003ca href=\"https://github.com/onesignal/react-onesignal/graphs/contributors\"\u003e\n\u003cimg src=\"https://user-images.githubusercontent.com/11739227/119415383-1d354700-bcb7-11eb-946d-01c40cd07010.png\" /\u003e\n\u003c/a\u003e\n\nEnjoy!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fonesignal%2Freact-onesignal","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fonesignal%2Freact-onesignal","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fonesignal%2Freact-onesignal/lists"}