{"id":13847316,"url":"https://github.com/bring-shrubbery/use-cookie-consent","last_synced_at":"2025-04-06T01:08:13.803Z","repository":{"id":39647334,"uuid":"370137073","full_name":"bring-shrubbery/use-cookie-consent","owner":"bring-shrubbery","description":"Smol (~1kB gzipped) hook for managing GDPR cookie consent state.","archived":false,"fork":false,"pushed_at":"2023-03-18T20:23:51.000Z","size":1637,"stargazers_count":401,"open_issues_count":4,"forks_count":15,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-05-02T05:06:45.379Z","etag":null,"topics":["cookies","gdpr","hooks","react"],"latest_commit_sha":null,"homepage":"https://use-cookie-consent.js.org","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/bring-shrubbery.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null},"funding":{"github":["bring-shrubbery"],"patreon":"bring_shrubbery","open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"custom":null}},"created_at":"2021-05-23T19:11:39.000Z","updated_at":"2024-03-10T00:48:50.000Z","dependencies_parsed_at":"2023-12-31T10:19:09.870Z","dependency_job_id":"c0a4dc32-ad81-4075-bd9e-168e5b359647","html_url":"https://github.com/bring-shrubbery/use-cookie-consent","commit_stats":null,"previous_names":["use-cookie-consent/use-cookie-consent-core","use-cookie-consent/use-cookie-consent"],"tags_count":33,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bring-shrubbery%2Fuse-cookie-consent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bring-shrubbery%2Fuse-cookie-consent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bring-shrubbery%2Fuse-cookie-consent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bring-shrubbery%2Fuse-cookie-consent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bring-shrubbery","download_url":"https://codeload.github.com/bring-shrubbery/use-cookie-consent/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247305300,"owners_count":20917194,"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":["cookies","gdpr","hooks","react"],"created_at":"2024-08-04T18:01:16.621Z","updated_at":"2025-04-06T01:08:13.782Z","avatar_url":"https://github.com/bring-shrubbery.png","language":"TypeScript","funding_links":["https://github.com/sponsors/bring-shrubbery","https://patreon.com/bring_shrubbery","https://www.buymeacoffee.com/bring.shrubbery"],"categories":["TypeScript"],"sub_categories":[],"readme":"# useCookieConsent hook for pure JavaScript projects\n\n[![Build](https://img.shields.io/github/checks-status/use-cookie-consent/use-cookie-consent-core/main?style=flat\u0026colorA=5C5C5C\u0026colorB=000000)](https://github.com/use-cookie-consent/use-cookie-consent-core/actions)\n[![NPM Version](https://img.shields.io/npm/v/@use-cookie-consent/core?style=flat\u0026colorA=5C5C5C\u0026colorB=000000)](https://www.npmjs.com/package/@use-cookie-consent/core)\n[![NPM Downloads](https://img.shields.io/npm/dm/@use-cookie-consent/core?style=flat\u0026colorA=5C5C5C\u0026colorB=000000)](https://www.npmjs.com/package/@use-cookie-consent/core)\n[![Codecov](https://img.shields.io/codecov/c/github/use-cookie-consent/use-cookie-consent-core?style=flat\u0026colorA=5C5C5C\u0026colorB=000000)](https://github.com/use-cookie-consent/use-cookie-consent-core/actions/workflows/codecov.yml)\n[![gzipped size](https://img.badgesize.io/https:/unpkg.com/@use-cookie-consent/core@latest/build/esm/index.js?label=gzipped\u0026compression=gzip\u0026style=flat\u0026color=000000)](https://unpkg.com/@use-cookie-consent/core@latest/build/esm/index.js)\n[![License](https://img.shields.io/npm/l/@use-cookie-consent/core?style=flat\u0026colorA=5C5C5C\u0026color=000000)](https://github.com/use-cookie-consent/use-cookie-consent-core/blob/main/LICENSE)\n\n[![\"Buy Me A Coffee\"](https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png)](https://www.buymeacoffee.com/bring.shrubbery)\n\n\u003e Headless state management for GDPR cookie consent\n\n- **Headless** - bring your own styles, we will provide the logic.\n- **Hook-based** - extremely intuitive for React developers, but can be used in any JavaScript application.\n- **Small** - Less than `2kB` gzipped.\n\n\u003cp align=\"center\"\u003e\n\u003cimg src=\"https://user-images.githubusercontent.com/29360707/145967135-eafd0467-9dd4-4496-b5f6-df5e6c1f40ba.png\" alt=\"carbon\" width=\"700px\" /\u003e\n\u003c/p\u003e\n\n## Library-specific packages\n\nThis repo was made to be framework-agnostic, so you can use it in any JavaScript project. If you use a UI library that we support, you should use the package for your library for best experience\n\n- [`@use-cookie-consent/react`](https://github.com/use-cookie-consent/use-cookie-consent-react)\n\n## Description\n\nThis package is following [this](https://gdpr.eu/cookies) GDPR cookie guide which describes what you need for GDPR compliance. This hook mainly focuses handling the consent state of the different types of cookies as described in \"Types of Cookies\" in [this](https://gdpr.eu/cookies) page. Summarizing the mentioned document, there are three different ways to classify cookies:\n\n- Cookie Duration\n  - Session cookies\n  - Persistent cookies\n- Cookie Provenance\n  - First-party cookies\n  - Third-party cookies\n- Cookie Purpose\n  - Strictly necessary cookies\n  - Preferences cookies\n  - Statistics cookies\n  - Marketing cookies\n\nThe hook in this repository will provide a way to manage these types of cookies.\n\n## Installation\n\n```bash\nnpm i @use-cookie-consent/core\n\nyarn add @use-cookie-consent/core\n\npnpm add @use-cookie-consent/core\n```\n\n⚠️ **Note:** to have React v18 support, temporarily install `@use-cookie-consent/core@0.4.0-dev.4`. All further development will support React v18, so this note will disappear in the future.\n\n## Usage in React\n\n```tsx\nimport { useCookieConsent } from '@use-cookie-consent/core';\n\nexport const YourComponent = () =\u003e {\n  const { consent, acceptAllCookies, declineAllCookies, acceptCookies } =\n    useCookieConsent();\n\n  return (\n    \u003cdiv\u003e\n      \u003ch3\u003e\n        {`Third-party cookies ${consent.thirdParty ? 'approved' : 'rejected'}`}\n      \u003c/h3\u003e\n      \u003ch3\u003e\n        {`First-party cookies ${consent.firstParty ? 'approved' : 'rejected'}`}\n      \u003c/h3\u003e\n\n      \u003cbutton onClick={acceptAllCookies}\u003eAccept all\u003c/button\u003e\n      \u003cbutton onClick={() =\u003e acceptCookies({ necessary: true, thirdParty: true })}\u003e\n        Accept third-party\n      \u003c/button\u003e\n      \u003cbutton onClick={() =\u003e acceptCookies({ necessary: true, firstParty: true })}\u003e\n        Accept first-party\n      \u003c/button\u003e\n      \u003cbutton onClick={declineAllCookies}\u003eReject all\u003c/button\u003e\n    \u003c/div\u003e\n  );\n};\n```\n\n### With custom cookie attributes\n```tsx\nimport { useCookieConsent } from '@use-cookie-consent/core';\n\nexport const YourComponent = () =\u003e {\n  const { consent, acceptAllCookies, declineAllCookies, acceptCookies } = useCookieConsent({ \n      consentCookieAttributes: { expires: 180  } // 180 days\n    }); \n\n  return (\n    // ...\n  );\n};\n```\n\nCookie attributes for the underlying js-cookie package, more info [here](https://github.com/js-cookie/js-cookie).\n\n## API\n\n### `useCookieConsent(options)`\n\n`useCookieConsent` is the main hook in this library. You call it whenever you need to accept, decline, set or get cookies - so anything to do with cookies.\n\n```ts\nuseCookieConsent({\n  defaultConsent?: CookieConsent,\n  consentCookieAttributes?: CookieAttributes;\n})\n```\n\nThis hook function returns following object:\n\n```ts\n{\n  consent: {\n    session?: boolean;\n    persistent?: boolean;\n    necessary?: boolean;\n    preferences?: boolean;\n    statistics?: boolean;\n    marketing?: boolean;\n    firstParty?: boolean;\n    thirdParty?: boolean;\n  };\n  acceptCookies: (cookies: CookieTypes) =\u003e void;\n  declineAllCookies: () =\u003e void;\n  acceptAllCookies: () =\u003e void;\n  didAcceptAll: () =\u003e boolean;\n  didDeclineAll: (opts?: CookieDeclineOptions) =\u003e boolean;\n  cookies: CookieWrapper;\n}\n```\n\n## Roadmap to v1\n\n- [ ] Monorepo\n- [x] Add package bundler ([rollup](https://rollupjs.org/) was added)\n- [ ] Add support for Storage API\n- [ ] Add support for custom cookie categories\n- [x] Create documentation website [here](https://use-cookie-consent.js.org/)\n- [ ] Create supporting library packages\n  - [x] React [here](https://github.com/use-cookie-consent/use-cookie-consent-react)\n  - [ ] Vue (planned)\n  - [ ] Svelte (planned)\n  - [ ] Solid (planned)\n  - [ ] Preact (planned)\n  - [ ] Alpine (planned)\n  - [ ] Lit (planned)\n- [ ] Change `CookiesWrapper` API to something that doesn't require a specific dependency (maybe just Storage API step?)\n\n## Contributing\n\nIf you want to contribute to this project, read our [contributing guidelines](https://github.com/use-cookie-consent/use-cookie-consent/blob/main/CONTRIBUTING.md) first.\n\n## Acknowledgements\n\nFollowing package was used as a starter for this project:\n\n- [easy-npm-package-react](https://github.com/bring-shrubbery/easy-npm-package-react)\n\n## Discussions and Questions\n\nFor non-issues please consider joining our Discord [here](https://discord.gg/pa8epvzJbb)!\n\n## Contributors\n\n- [Antoni Silvestrovic (author)](https://github.com/bring-shrubbery)\n\n## License\n\n[MIT](https://github.com/bring-shrubbery/use-cookie-consent/blob/master/LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbring-shrubbery%2Fuse-cookie-consent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbring-shrubbery%2Fuse-cookie-consent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbring-shrubbery%2Fuse-cookie-consent/lists"}