{"id":14991027,"url":"https://github.com/ryanhefner/react-contentful","last_synced_at":"2025-04-04T18:05:11.693Z","repository":{"id":38280060,"uuid":"169603378","full_name":"ryanhefner/react-contentful","owner":"ryanhefner","description":"📰 A React component library that makes it super simple to compose Contentful content into your sites and applications.","archived":false,"fork":false,"pushed_at":"2025-03-26T05:13:26.000Z","size":13212,"stargazers_count":67,"open_issues_count":54,"forks_count":11,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-28T17:08:32.334Z","etag":null,"topics":["contentful","contentful-api","contentful-js-sdk","react","react-component","react-hooks","reactjs"],"latest_commit_sha":null,"homepage":"https://ryanhefner.github.io/react-contentful","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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":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-02-07T16:30:32.000Z","updated_at":"2024-11-07T05:31:12.000Z","dependencies_parsed_at":"2024-06-18T17:01:56.804Z","dependency_job_id":"dfbef0d5-6f3e-4f83-a828-98cb9af24e5a","html_url":"https://github.com/ryanhefner/react-contentful","commit_stats":{"total_commits":377,"total_committers":4,"mean_commits":94.25,"dds":"0.30503978779840846","last_synced_commit":"333128bfc6e4421c352ed80293e379b18ee8e685"},"previous_names":[],"tags_count":78,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ryanhefner%2Freact-contentful","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ryanhefner%2Freact-contentful/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ryanhefner%2Freact-contentful/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ryanhefner%2Freact-contentful/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ryanhefner","download_url":"https://codeload.github.com/ryanhefner/react-contentful/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247226213,"owners_count":20904465,"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":["contentful","contentful-api","contentful-js-sdk","react","react-component","react-hooks","reactjs"],"created_at":"2024-09-24T14:21:20.319Z","updated_at":"2025-04-04T18:05:11.665Z","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-contentful\n\n[![npm](https://img.shields.io/npm/v/react-contentful?style=flat-square)](https://www.pkgstats.com/pkg:react-contentful)\n[![NPM](https://img.shields.io/npm/l/react-contentful?style=flat-square)](LICENSE)\n[![npm](https://img.shields.io/npm/dt/react-contentful?style=flat-square)](https://www.pkgstats.com/pkg:react-contentful)\n[![Coveralls github](https://img.shields.io/coveralls/github/ryanhefner/react-contentful?style=flat-square)](https://coveralls.io/github/ryanhefner/react-contentful)\n[![codecov](https://codecov.io/gh/ryanhefner/react-contentful/branch/master/graph/badge.svg)](https://codecov.io/gh/ryanhefner/react-contentful)\n[![CircleCI](https://img.shields.io/circleci/build/github/ryanhefner/react-contentful?style=flat-square)](https://circleci.com/gh/ryanhefner/react-contentful)\n![Snyk Vulnerabilities for GitHub Repo](https://img.shields.io/snyk/vulnerabilities/github/ryanhefner/react-contentful?style=flat-square)\n\n\nA React component library that makes it super simple to compose Contentful\ncontent into your sites and applications.\n\n\n## Install\n\nVia [npm](https://npmjs.com/package/react-contentful)\n\n```sh\nnpm install react-contentful\n```\n\nVia [Yarn](https://yarn.pm/react-contentful)\n\n```sh\nyarn add react-contentful\n```\n\n\n## How to use\n\nThe `ContentfulProvider` can provide a global context to your site or applications\nallowing you to connect to your Contentful content. By using either the `Query`\ncomponent, or writing your own Contentful client consumer component which offers\naccess to the `ContentfulClient` directly by using `withContentful`, all queries\ncan be performed against Contentful that are available through their existing\nJavascript SDK.\n\n\n### `ContentfulProvider`\n\n```js\nimport React from 'react';\nimport { ContentfulClient, ContentfulProvider } from 'react-contentful';\nimport Page from './Page';  // @see Page component defined in `useContentful` or `Query` examples below\n\nconst contentfulClient = new ContentfulClient({\n  accessToken: '[Your Contentful Content Delivery API - access token]',\n  space: '[Your Contentful Space ID]',\n});\n\nconst App = () =\u003e (\n  \u003cContentfulProvider client={contentfulClient}\u003e\n    \u003cRouter\u003e\n      \u003cSwitch\u003e\n        \u003cRoute path=\"/:slug*\" component={Page} /\u003e\n      \u003c/Switch\u003e\n    \u003c/Router\u003e\n  \u003c/ContentfulProvider\u003e\n);\n\nexport default App;\n```\n\n\n### `useContentful` - React Hook\n\nIn this example, we are using the `useContentful` hook that accepts query params\nthat can be used to directly query Contentul and supply the results in the `data`\nobject returned.\n\n```js\nimport React from 'react';\nimport { useContentful } from 'react-contentful';\n\nconst Page = props =\u003e {\n  const { data, error, fetched, loading } = useContentful({\n    contentType: 'Page',\n    query: {\n      'fields.slug[in]': `/${props.match.slug || ''}`,\n    }\n  });\n\n  if (loading || !fetched) {\n    return null;\n  }\n\n  if (error) {\n    console.error(error);\n    return null;\n  }\n\n  if (!data) {\n    return \u003cp\u003ePage does not exist.\u003c/p\u003e;\n  }\n\n  // See the Contentful query response\n  console.debug(data);\n\n  // Process and pass in the loaded `data` necessary for your page or child components.\n  return (\n    ...\n  );\n}\n```\n\n\n### `Query`\n\nIn this example, the `Query` component accepts a `query` parameter that\nfilters `Page` content types from Contentful based on the `slug` field set on\npublished `Page` content models.\n\n\n```js\nimport React from 'react';\nimport { Query } from 'react-contentful';\n\nconst Page = props =\u003e (\n  \u003cQuery\n    contentType=\"Page\"\n    query={{\n      'fields.slug[in]': `/${props.match.slug || ''}`,\n    }}\n  \u003e\n    {({data, error, fetched, loading}) =\u003e {\n      if (loading || !fetched) {\n        return null;\n      }\n\n      if (error) {\n        console.error(error);\n        return null;\n      }\n\n      if (!data) {\n        return \u003cp\u003ePage does not exist.\u003c/p\u003e;\n      }\n\n      // See the Contentful query response\n      console.debug(data);\n\n      // Process and pass in the loaded `data` necessary for your page or child components.\n      return (\n        ...\n      );\n    }}\n  \u003c/Query\u003e\n);\n\nexport default Page;\n```\n\n\n## Using Next.js?\n\nIf you like what you see above, you might like [next-contentful](https://github.com/ryanhefner/next-contentful),\nwhich lets you easily add `react-contentful` to your Next.js app, making it easy\nto ensure that all your `Query` instances render awesomely server-side.\n\n\n## Components Reference\n\nBelow are the following components and classes that are availabe in this package\nthat makes it easy to integrate Contentful into your site or application.\n\n\n### `ContentfulProvider`\n\nProvider that offers accesss to a centralized `ContentfulClient` that not only\ncan make all your Contentful requests, but also handles caching those requests\nduring your session to keep things optimized and fast.\n\n\n| Prop             | Default | Description                                                                                                                                                            |\n| ---------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `client`         | `null`  | Required for children that utilize `withContentful` to make requests to Contentful.                                                                                    |\n| `locale`         | `en-US` | Default `locale` to use for requests against the Contentful API.                                                                                                       |\n| `renderPromises` | `null`  | Not used during normal use, but utilized by other libraries like [`next-contentful`](https://github.com/ryanhefner/next-contentful) for use during server-side rendering. |\n\n\n### `ContentfulClient`\n\nInstance of Contentful client that is for making requests and caching responses.\n\n\n| Options       | Default                 | Description                                                                                                                      |\n| ------------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------- |\n| `space`       | `null`                  | ID of the Contentful space that queries will be submitted to.                                                                    |\n| `accessToken` | `null`                  | Access token used for client initialization.                                                                                     |\n| `environment` | `master`                | Contentful environment to make requests to.                                                                                      |                                                                          |\n| `host`        | `cdn.contentful.com`    | Host to use for requests. Accepts either, `cdn.contentful.com` or `preview.contentful.com`.                                      |\n| `cache`       | `new ContentfulCache()` | Cache used for caching responses during a session, as well as rehydrating the client/app when used during server-side rendering. |\n| `ssrMode`     | `false`                 | Flag to specify when client is being used during server-side rendering.                                                          |\n\n\n\u003e The `ContentfulClient` is an extension of the Contentful Delivery API SDK. For more information about what options are available when creating a client, along with other useful insights, check out the [Official Contentful documentation](https://contentful.github.io/contentful.js/contentful/7.8.2/contentful.html#.createClient).\n\n\n### `ContentfulCache`\n\nCache instance used for caching responses in memory during a session, along with\nbuilding up a cache of responses for responses used to render/rehydrate the app\nwhen used during server-side rendering. You would typically not have to work with\nthis class directly, unless you are rolling your own server-side rendering solution\nor have some ideas around warming the cache. Otherwise, you should check out\n[`next-contentful`](https://github.com/ryanhefner/next-contentful) if you’re working\non a React/Node/Express app.\n\n\n| Arguments | Default | Description                                        |\n| --------- | ------- | -------------------------------------------------- |\n| `cache`   | `null`  | Initializes a new `Map` instance to use for cache. |\n\n\n### `useContentful`\n\nBased on the previous `Query` component, `useContentful` accepts the following options to generate your Contentful queries.\n\n| Props         | Default                                     | Description |\n| ------------- | ------------------------------------------- | ----------- |\n| `contentType` | `null`                                      | Content type associated with the content model that you are querying for within Contentful. Required for non-`id` queries. Results in an array of results returned. |\n| `id`          | `null`                                      | Entry id associated with the content model in Contentful. Returns a single data model from Contentful if it exists. |\n| `include`     | `10`                                        | Depth of referenced content to include in the query. Defaults to `10`. |\n| `query`       | `null`                                      | Query object used for defining the search parameters to use for the request. You can reference all available options via [Contentful official documentation](https://www.contentful.com/developers/docs/references/content-delivery-api/#/reference/search-parameters) |\n| `parser`      | `(data, props) =\u003e data`                     | Parser to use for manipulating the response data before being pass to the children/returned via callbacks. |\n| `skip`        | `false`                                     | Flag used to skip the `Query` instance when being referenced during server-side rendering. |\n\n\n### `Query`\n\nThis is where the magic happens. You can compose `Query` wherever you need to\nreference or conditionally render content based on Contentful data. `Query`s can\nbe used standalone, or to wrap content that is reliant on the data.\n\n\n| Props         | Default                                     | Description |\n| ------------- | ------------------------------------------- | ----------- |\n| `contentType` | `null`                                      | Content type associated with the content model that you are querying for within Contentful. Required for non-`id` queries. Results in an array of results returned. |\n| `id`          | `null`                                      | Entry id associated with the content model in Contentful. Returns a single data model from Contentful if it exists. |\n| `include`     | `10`                                        | Depth of referenced content to include in the query. Defaults to `10`. |\n| `query`       | `null`                                      | Query object used for defining the search parameters to use for the request. You can reference all available options via [Contentful official documentation](https://www.contentful.com/developers/docs/references/content-delivery-api/#/reference/search-parameters) |\n| `parser`      | `(data, props) =\u003e data`                     | Parser to use for manipulating the response data before being pass to the children/returned via callbacks. |\n| `skip`        | `false`                                     | Flag used to skip the `Query` instance when being referenced during server-side rendering. |\n| `onError`     | `({ data, error, fetched, loading }) =\u003e {}` | Callback for when an error is encountered during the request. `fetched` will be set to `true` and `error` will be set. |\n| `onLoad`      | `({ data, error, fetched, loading }) =\u003e {}` | Callback for when the response has completed. `fetched` will be set to `true` and `data` will be set. |\n| `onRequest`   | `({ data, error, fetched, loading }) =\u003e {}` | Callback for when the request has been initiated. `loading` will be set to `true` and all other values will be `null` or `false`. |\n\n\n### `withContentful`\n\nHigher-order component that is available in case you want to build your own Contentful\nready components. Used by the `Query` component for providing access to the `ContentfulContext`.\n\n\n```js\nimport { withContentful } from 'react-contentful';\n\nconst YourComponent = ({ contentful }) =\u003e {\n  const { client, locale, renderPromises } = contentful;\n\n  return (\n    ...\n  );\n};\n\nexport default withContentful(YourComponent);\n````\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-contentful","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fryanhefner%2Freact-contentful","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fryanhefner%2Freact-contentful/lists"}