{"id":13649944,"url":"https://github.com/gremo/react-directus","last_synced_at":"2025-04-05T12:06:31.618Z","repository":{"id":37047814,"uuid":"364084896","full_name":"gremo/react-directus","owner":"gremo","description":"A set of React components and utilities for Directus Headless CMS","archived":false,"fork":false,"pushed_at":"2025-03-28T23:15:40.000Z","size":1942,"stargazers_count":123,"open_issues_count":14,"forks_count":14,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-29T00:23:16.647Z","etag":null,"topics":["directus","react"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"isc","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gremo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"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,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-05-03T23:12:17.000Z","updated_at":"2025-03-11T19:21:02.000Z","dependencies_parsed_at":"2024-01-21T11:23:46.641Z","dependency_job_id":"1919c121-3402-4ed4-a482-f07d4c6c3a91","html_url":"https://github.com/gremo/react-directus","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gremo%2Freact-directus","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gremo%2Freact-directus/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gremo%2Freact-directus/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gremo%2Freact-directus/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gremo","download_url":"https://codeload.github.com/gremo/react-directus/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247332605,"owners_count":20921853,"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":["directus","react"],"created_at":"2024-08-02T02:00:31.387Z","updated_at":"2025-04-05T12:06:31.586Z","avatar_url":"https://github.com/gremo.png","language":"TypeScript","funding_links":["https://paypal.me/marcopolichetti"],"categories":["Integration","TypeScript"],"sub_categories":["Community"],"readme":"\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://directus.io\"\u003e\u003cimg alt=\"Directus logo\" src=\"https://directus.io/assets/favicon.svg\" width=\"120\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003e\n  react-directus\n\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.npmjs.com/package/react-directus\"\u003e\u003cimg alt=\"NPM version\" src=\"https://img.shields.io/npm/v/react-directus.svg\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/package/react-directus\"\u003e\u003cimg alt=\"NPM downloads\" src=\"https://img.shields.io/npm/dw/react-directus.svg\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://paypal.me/marcopolichetti\" target=\"_blank\"\u003e\u003cimg src=\"https://img.shields.io/badge/Donate-PayPal-ff3f59.svg\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg alt=\"GitHub last commit\" src=\"https://img.shields.io/github/last-commit/gremo/react-directus\"\u003e\n  \u003ca href=\"https://github.com/gremo/react-directus/actions/workflows/test.yaml\"\u003e\u003cimg alt=\"GitHub Workflow Status\" src=\"https://img.shields.io/github/actions/workflow/status/gremo/react-directus/test.yaml\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/gremo/react-directus/issues\"\u003e\u003cimg alt=\"GitHub issues\" src=\"https://img.shields.io/github/issues/gremo/react-directus.svg\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/gremo/react-directus/pulls\"\u003e\u003cimg alt=\"GitHub pull requests\" src=\"https://img.shields.io/github/issues-pr/gremo/react-directus\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  A set of React components and utilities for \u003ca href=\"https://directus.io\"\u003eDirectus\u003c/a\u003e Headless CMS.\n\u003c/p\u003e\n\n## 🚀 Quick start\n\nInstall this library along with `@directus/sdk@` (version 10 or below):\n\n\u003e **Note**: Directus SDK version 11 and upwards are currently not supported, but active work is in progress to add support for these versions in future releases.\n\n```bash\nnpm install react-directus @directus/sdk@^10\n```\n\nThe `\u003cDirectusProvider\u003e` component makes the [Directus JavaScript SDK](https://docs.directus.io/reference/sdk/) available to any nested components that need to access it. The provider accepts the following props:\n\n- `apiUrl`: the URL of your Directus API\n- `options` (optional): an object containing the [Directus client options](https://docs.directus.io/reference/sdk/#reference)\n- `autoLogin` (optional): if `true`, the SDK will try to login using the `accessToken` stored in the browser's local storage\n- `onAutoLoginError` (optional): a callback function that is called when the auto-login fails\n\n```jsx\nimport { App } from './App';\nimport { DirectusProvider } from 'react-directus';\nimport { createRoot } from 'react-dom/client';\n\nconst root = createRoot(document.getElementById('root'));\n\nroot.render(\n  \u003cDirectusProvider apiUrl=\"https://api.example.com\" options={{}}\u003e\n    \u003cApp /\u003e\n  \u003c/DirectusProvider\u003e\n);\n```\n\nWith **TypeScript**, you can use the optional generic collection type for Directus, as described in the [Directus TypeScript documentation](https://docs.directus.io/reference/old-sdk.html#typescript):\n\n```jsx\nimport { App } from './App';\nimport { DirectusProvider } from 'react-directus';\nimport { createRoot } from 'react-dom/client';\n\nimport MyCollections from './types';\n\nconst root = createRoot(document.getElementById('root'));\n\nroot.render(\n  \u003cDirectusProvider\u003cMyCollections\u003e apiUrl=\"https://api.example.com\" options={{}}\u003e\n    \u003cApp /\u003e\n  \u003c/DirectusProvider\u003e\n);\n```\n\n## ⚙️ Hooks\n\n### `useDirectus`\n\nAfter adding the provider, you can access the configured client anywhere in the app, using the `useDirectus` hook:\n\n```jsx\nimport { useEffect, useState } from 'react';\nimport { useDirectus } from 'react-directus'\n\nexport const TodoList = () =\u003e {\n  // Get the Directus SDK object\n  const { directus } = useDirectus();\n  const [todos, setTodos] = useState([]);\n\n  useEffect(() =\u003e {\n    const fetchTodos = async () =\u003e {\n      const todos = (await directus.items('todos').readMany()).data;\n      setTodos(todos);\n    };\n\n    fetchTodos();\n  }, [directus]);\n\n  return todos.map(item =\u003e \u003cTodoItem key={item.id} item={item} /\u003e);\n};\n```\n\n### `useDirectusAuth`\n\nThe `useDirectusAuth` hook provides a few methods for working with the [Directus Authentication API](https://docs.directus.io/reference/old-sdk.html#authentication):\n\n- `login` - a function that accepts an email and password and returns a promise that resolves to the user object if the login is successful or rejects with an error otherwise\n- `logout` - a function that logs out the current user\n- `user` - the current user object\n- `authState` - the current authentication state, one of `loading` (the initial state), `logged-in` or `logged-out`\n\n```jsx\nimport { useDirectusAuth } from 'react-directus';\nimport { FormEvent } from 'react';\n\nconst Login = () =\u003e {\n  const { login } = useDirectusAuth();\n\n  const handleSubmit = (e: FormEvent\u003cHTMLFormElement\u003e) =\u003e {\n    e.preventDefault();\n\n    const { email, password } = e.currentTarget.elements;\n    login(email.value, password.value).catch(err =\u003e {\n      console.error(err);\n    });\n  };\n\n  return (\n    \u003cform onSubmit={handleSubmit}\u003e\n      \u003cinput type='email' name='email' /\u003e\n      \u003cinput type='password' name='password' /\u003e\n      \u003cbutton type='submit'\u003eLogin\u003c/button\u003e\n    \u003c/form\u003e\n  );\n};\n\nexport default Login;\n\n```\n\n## 🧩 Components (so far...)\n\nThis package contains a component for working with Direcuts [files](https://docs.directus.io/reference/files/). It is configured for using the `apiUrl` and `accessToken` specified in the provider. Hopefully, more will come in the future 🤗.\n\n\u003e **Note**: The components can also be used in a \"standalone\" way, meaning that they are not bound to the `apiUrl` specified in the provider. In that case, they both accept an `apiUrl` and an optional `accessToken` prop.\n\n### `\u003cDirectusFile\u003e`\n\nComputes the URL of the given resource `asset`, rendering it using the `render` prop:\n\n- `apiUrl`: the API URL of the Directus instance(can be omitted if the provider is used)\n- `accessToken`: the access token to use for authentication (can be omitted if the provider is used)\n- `asset`: the asset representing the resource (`string` or `object` with an `id` property)\n- `download`: force browser to download the asset (force the `Content-Disposition` header)\n- `directusTransform`: an object with the Directus [transform](https://docs.directus.io/reference/files/#transform) options or a preset key\n- `filename`: the filename to use for the asset [SEO](https://docs.directus.io/reference/files/#accessing-a-file)\n- `render`: a function (which receives an object with the `url` property) that provides the component to render\n\n#### Example with custom transform\n\n```jsx\nimport { DirectusFile } from 'react-directus';\n\nexport const MyImage = ({ imageId }) =\u003e (\n  \u003cDirectusFile\n    asset={imageId}\n    directusTransforms={{ width: 200, height: 200 }}\n    render={({ url }) =\u003e \u003cimg src={url} /\u003e}\n  /\u003e\n);\n```\n\n#### Example for downloading a file\n\n```jsx\nimport { DirectusFile } from 'react-directus';\n\nexport const MyImage = ({ imageId }) =\u003e (\n  \u003cDirectusFile\n    asset={imageId}\n    download\n    filename=\"my-file-name.jpg\"\n    render={({ url, filename }) =\u003e \u003ca href={url} download={filename}\u003eDownload\u003c/a\u003e}\n  /\u003e\n);\n```\n\n## 📱 React Native\n\nTo make the project fully compatible with React Native you need to install the [localstorage-polyfill](https://www.npmjs.com/package/localstorage-polyfill) package:\n\n```bash\nnpm install localstorage-polyfill\n```\n\nThen import the module **before any other import** and force the storage mode \"LocalStorage\" in your Directus instance:\n\n```jsx\nimport 'localstorage-polyfill';\nimport { DirectusProvider } from 'react-directus';\nimport { View } from 'react-native';\n\nexport default function App({}) {\n    return (\n        \u003cDirectusProvider\n            apiUrl='https://api.example.com'\n            options={{ storage: { mode: 'LocalStorage' } }}\n        \u003e\n            \u003cView /\u003e\n        \u003c/DirectusProvider\u003e\n    )\n}\n```\n\nIn future releases, a solution using `AsyncStorage` or an encrypted secure storage option is planned.\n\n## ❤️ Contributing\n\nAll types of contributions are encouraged and valued. See the [Contributing](CONTRIBUTING.md) guidelines, the community looks forward to your contributions!\n\n## 📘 License\n\nThis project is released under the under terms of the [ISC License](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgremo%2Freact-directus","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgremo%2Freact-directus","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgremo%2Freact-directus/lists"}