{"id":15397018,"url":"https://github.com/ryanhefner/react-prismic","last_synced_at":"2025-04-16T00:23:13.388Z","repository":{"id":35101377,"uuid":"201488758","full_name":"ryanhefner/react-prismic","owner":"ryanhefner","description":"📰 Easily compose Prismic requests and data into your React applications.","archived":false,"fork":false,"pushed_at":"2023-01-06T02:06:26.000Z","size":2045,"stargazers_count":3,"open_issues_count":13,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-02-23T18:11:21.577Z","etag":null,"topics":["api","fetch","prismic","prismic-javascript","query","react","react-component","react-component-library","react-hoc"],"latest_commit_sha":null,"homepage":"https://www.pkgstats.com/pkg:@ryanhefner/react-prismic","language":"JavaScript","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/ryanhefner.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null},"funding":{"github":"ryanhefner","patreon":"ryanhefner","open_collective":"ryanhefner","ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"custom":null}},"created_at":"2019-08-09T14:59:49.000Z","updated_at":"2023-03-04T04:12:37.000Z","dependencies_parsed_at":"2023-01-15T13:52:22.378Z","dependency_job_id":null,"html_url":"https://github.com/ryanhefner/react-prismic","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ryanhefner%2Freact-prismic","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ryanhefner%2Freact-prismic/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ryanhefner%2Freact-prismic/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ryanhefner%2Freact-prismic/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ryanhefner","download_url":"https://codeload.github.com/ryanhefner/react-prismic/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241290226,"owners_count":19939239,"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":["api","fetch","prismic","prismic-javascript","query","react","react-component","react-component-library","react-hoc"],"created_at":"2024-10-01T15:35:51.183Z","updated_at":"2025-03-01T00:32:30.235Z","avatar_url":"https://github.com/ryanhefner.png","language":"JavaScript","funding_links":["https://github.com/sponsors/ryanhefner","https://patreon.com/ryanhefner","https://opencollective.com/ryanhefner"],"categories":[],"sub_categories":[],"readme":"# 📰 react-prismic\n\n[![npm](https://img.shields.io/npm/v/@ryanhefner/react-prismic?style=flat-square)](https://www.npmjs.com/package/@ryanhefner/react-prismic)\n[![NPM](https://img.shields.io/npm/l/@ryanhefner/react-prismic?style=flat-square)](https://www.npmjs.com/package/@ryanhefner/react-prismic)\n[![npm](https://img.shields.io/npm/dt/@ryanhefner/react-prismic?style=flat-square)](https://www.npmjs.com/package/@ryanhefner/react-prismic)\n\nEasily compose [Prismic](https://prismic.io) requests and data into your React applications.\n\n\n## Install\n\nVia [npm](https://npmjs.com/package/@ryanhefner/react-prismic)\n\n```sh\nnpm install --save @ryanhefner/react-prismic\n```\n\nVia [Yarn](https://yarn.pm/@ryanhefner/react-prismic)\n\n```sh\nyarn add @ryanhefner/react-prismic\n```\n\n\n## How to use\n\nThe goal of `react-prismic` is to take the thinking out of initializing a client\nand making requests, and focused on making it easy to quickly setup and access\nthe data that you need from [Prismic](https://prismic.io) in your React apps.\n\n\n### `PrismicProvider`\n\nThe `PrismicProvider` allows you to define a scope/client to used for your next\n`PrismicQuery`s. In most setups, you’ll probably only need one instance of this,\ncomposed around your main app. But, if you happen to have another section or component\nor your app that needs to interface with a different Prismic repo, you can compose\nthese wherever you like and all nested `PrismicQuery`s will use the client for\neach.\n\n#### Props\n\n* `repo: string` - The name of the Prismic repo you plan on querying.\n\n\u003e This is name that is before `.prismic.io` when you are looking at your repo in Prismic.\n\n\u003e `repo` should be good for 94.6% of instances when using this class. If you want\n\u003e to get fancy, the following `props` are also available for you.\n\n* `api: PrismicApi` - If you’re already initialzing an instance of the Prismic API outside of the `PrismicProvider`, you can pass that in to keep using that same one.\n\n\u003e If you have a reason to override the Prismic API witth your own logic, like\n\u003e hitting your own custom endpoint, it should be assumed that your instance of\n\u003e the Prismic API matches the interface of the original.\n\n* `client: PrismicClient` - Client that will be used to make requests against Prismic.\n\n* `cache: Cache | iterable | string` - Cache instance to initialize the `client` cache with.\n\n* `renderPromises: RenderPromises` - Passed in via [`next-prismic`](https://github.com/ryanhefner/next-prismic) for requesting and rendering requests during server-side rendering.\n\n\n#### Example\n\n```js\nimport React from 'react';\nimport { PrismicProvider } from 'react-prismic';\n\nimport Component from './Component';\n\nconst App = () =\u003e (\n  \u003cPrismicProvider repo=\"[your-prismic-repo]\"\u003e\n    \u003cComponent /\u003e\n  \u003c/PrismicProvider\u003e\n);\n```\n\n\n### `PrismicQuery`\n\nThis is where the magic happens ✨ Easily compose Prismic queries into your React applications.\nInstead of getting crafty with some unmappable props -\u003e method fiasco, I’ve just\nexposed all the available methods from the [`Prismic - ResolvedApi`](https://prismicio.github.io/prismic-javascript/classes/resolvedapi.html)\nas props to make it easy to choose the method that best suits your needs without\nanother API to learn.\n\nThe only caveat to this is, instead of just passing in an array of arguments to\nthe methods, I’ve mapped an object to the function args. It feels more React-y\nwhen using it, but I’m also open to a discussion on a better way to handle these\nsince the prop list is rather verbose right now.\n\n\u003e For more details about the Prismic API, I highly recommend that you reference\n\u003e their [`prismic-javascript` documentation](https://prismicio.github.io/prismic-javascript/index.html).\n\n#### Props\n\n* `currentExperience: boolean`\n\n* `everything: boolean`\n\n* `getBookmark: { bookamark, options?, callback }`\n\n* `getByID: { id, options?, callback? }`\n\n* `getByIDs: { ids, options?, callback? }`\n\n* `getByUID: { type, uid, options?, callback? }`\n\n* `getSingle: { type, options?, callback? }`\n\n* `master: boolean`\n\n* `previewSession: { token, linkResolver, defaultUrl, callback? }`\n\n* `query: { query, options?, callback? }`\n\n* `queryFirst: { query, options?, callback? }`\n\n* `prismicRef: { label }` - This is the one method that doesn’t map directly to the existing API, since it conflicts with React’s native `ref` prop.\n\n* `skip: boolean` - Skip the request during server-side rendering.\n\n* `onError: ({ data, error, loading, fetch }) =\u003e {}` - Called when an error is encountered during the request.\n\n* `onLoad: ({ data, error, loading, fetched }) =\u003e {}` - Called when the request has finished loading.\n\n* `onRequest: ({ data, error, loading, fetched }) =\u003e {}` - Called when the request has been initiated.\n\n\n#### Example\n\n```js\nimport React from 'react';\nimport { PrismicQuery } from 'react-prismic';\nimport { RichText } from 'prismic-reactjs';\n\nconst Component = () =\u003e (\n  \u003cReact.Fragment\u003e\n    \u003cheader\u003e\n      \u003cPrismicQuery getSingle={{ type: 'header' }}\u003e\n        {({ data, error, fetched }) =\u003e {\n          if (!fetched) {\n            return null;\n          }\n\n          if (error) {\n            console.error(error);\n            return null;\n          }\n\n          const {\n            name,\n            logo,\n            logoLink,\n            headerLinks,\n          } = data.data;\n\n          return (\n            \u003cReact.Fragment\u003e\n              \u003cdiv className=\"header__logo\"\u003e\n                \u003ca href={logoLink.url}\u003e\n                  {logo \u0026\u0026 \u003cimg src={logo.url} alt={name} /\u003e}\n                  \u003ch1\u003e{name}\u003c/h1\u003e\n                \u003c/a\u003e\n              \u003c/div\u003e\n              \u003cdiv className=\"header__links\"\u003e\n                {headerLinks \u0026\u0026 headerLinks.value.map(headerLink =\u003e (\n                  \u003ca href={headerLink.link.value.url}\u003e\n                    {headerLink.link_title.value.text}\n                  \u003c/a\u003e\n                ))}\n              \u003c/div\u003e\n            \u003c/React.Fragment\u003e\n          );\n        }}\n      \u003c/PrismicQuery\u003e\n    \u003c/header\u003e\n    \u003cmain\u003e\n      \u003cPrismicQuery\u003e\n        {({ data, error, fetched}) =\u003e {\n          ...\n        }}\n      \u003c/PrismicQuery\u003e\n    \u003c/main\u003e\n    \u003cfooter\u003e\n      \u003cPrismicQuery getSingle={{ type: 'footer' }}\u003e\n        {({ data, error, fetched }) =\u003e {\n          ...\n        }}\n      \u003c/PrismicQuery\u003e\n    \u003c/footer\u003e\n  \u003c/React.Fragment\u003e\n);\n\nexport default Component;\n```\n\n\n### `withPrismic`\n\nHave another type of component in mind to use within your `PrismicProvider`?\nBy using `withPrismic` you can expose the `prismic` context to your component\nand utilize whatever is available. (Pssst...this is what the `PrismicQuery`\ncomponent is using.)\n\n\n#### Context\n\n* `client: PrismicClient` - Use this to make requests, access the cache, or whatever else you might want to do.\n\n* `renderPromises: RenderPromises` - This is typically only set during server-side rendering (used by `next-prismic`), but available just letting you know in case you might need it.\n\n\n#### Example\n\n```js\nimport React from 'react';\nimport { withPrismic } from 'react-prismic';\n\nconst Component = ({ prismic }) =\u003e {\n  const {\n    client,\n  } = prismic;\n\n  [do something with client]\n};\n\nexport default withPrismic(Component);\n\n```\n\n\n### `PrismicClient`\n\nAgain, this is one of those classes that you’ll rarely have to interface with\nsince the `PrismicProvider` takes care of instantiating an instance for you. But,\nin an effort of making truly open, open source software, here is a little breakdown\nof the `PrismicClient`\n\n#### Options\n\n* `api: PrismicClient` - Available for the wild ones, the dreamers, the mavericks. Pass in your own Prismic API interface in the event you need to do some low-level shenanigans.\n\n* `cache: Cache` - Internally this package uses [`creature-cache`](https://github.com/ryanhefner/creature-cache), but there’s nothing preventing you from using something else, as long as you implement your’s with the same interface.\n\n* `repo: string` - String of the Prismic repo you are planning to access.\n\n\u003e This is name that is before `.prismic.io` when you are looking at your repo in Prismic. (ex. `your-repo.prismic.io`, the `repo` would be `your-repo`)\n\n\n#### Example\n\n```js\nimport { PrismicClient } from 'react-prismic';\n\nconst prismicClient = new PrismicClient({\n  repo: '[name of prismic repo, ex. `your-repo` of your-repo.prismic.io]'\n});\n```\n\n\n## Using Next.js?\n\nIf you like what you see above, you might like [@ryanhefner/next-prismic](https://github.com/ryanhefner/next-prismic),\nwhich lets you easily add `react-prismic` to your Next.js app, making it easy\nto ensure that all your `PrismicQuery` instances render awesomely server-side.\n\n\n## License\n\n[MIT](LICENSE) © [Ryan Hefner](https://www.ryanhefner.com)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fryanhefner%2Freact-prismic","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fryanhefner%2Freact-prismic","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fryanhefner%2Freact-prismic/lists"}