react-directus

A set of React components and utilities for Directus Headless CMS.

🚀 Quick start

Install this library along with @directus/sdk@ (version 10 or below):

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.

npm install react-directus @directus/sdk@^10

The <DirectusProvider> component makes the Directus JavaScript SDK available to any nested components that need to access it. The provider accepts the following props:

• apiUrl: the URL of your Directus API
• options (optional): an object containing the Directus client options
• autoLogin (optional): if true, the SDK will try to login using the accessToken stored in the browser's local storage
• onAutoLoginError (optional): a callback function that is called when the auto-login fails

import{App}from'./App';import{DirectusProvider}from'react-directus';import{createRoot}from'react-dom/client';constroot=createRoot(document.getElementById('root'));root.render(<DirectusProviderapiUrl="https://api.example.com"options={{}}><App/></DirectusProvider>);

With TypeScript, you can use the optional generic collection type for Directus, as described in the Directus TypeScript documentation:

import{App}from'./App';import{DirectusProvider}from'react-directus';import{createRoot}from'react-dom/client';importMyCollectionsfrom'./types';constroot=createRoot(document.getElementById('root'));root.render(<DirectusProvider<MyCollections> apiUrl="https://api.example.com" options={{}}><App/></DirectusProvider>);

⚙️ Hooks

useDirectus

After adding the provider, you can access the configured client anywhere in the app, using the useDirectus hook:

import{useEffect,useState}from'react';import{useDirectus}from'react-directus'exportconstTodoList=()=>{// Get the Directus SDK objectconst{ directus }=useDirectus();const[todos,setTodos]=useState([]);useEffect(()=>{constfetchTodos=async()=>{consttodos=(awaitdirectus.items('todos').readMany()).data;setTodos(todos);};fetchTodos();},[directus]);returntodos.map(item=><TodoItemkey={item.id}item={item}/>);};

useDirectusAuth

The useDirectusAuth hook provides a few methods for working with the Directus Authentication API:

• 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
• logout - a function that logs out the current user
• user - the current user object
• authState - the current authentication state, one of loading (the initial state), logged-in or logged-out

import{useDirectusAuth}from'react-directus';import{FormEvent}from'react';constLogin=()=>{const{ login }=useDirectusAuth();consthandleSubmit=(e: FormEvent<HTMLFormElement>)=>{e.preventDefault();const{ email, password }=e.currentTarget.elements;login(email.value,password.value).catch(err=>{console.error(err);});};return(<formonSubmit={handleSubmit}><inputtype='email'name='email'/><inputtype='password'name='password'/><buttontype='submit'>Login</button></form>);};exportdefaultLogin;

🧩 Components (so far...)

This package contains a component for working with Direcuts files. It is configured for using the apiUrl and accessToken specified in the provider. Hopefully, more will come in the future 🤗.

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.

<DirectusFile>

Computes the URL of the given resource asset, rendering it using the render prop:

• apiUrl: the API URL of the Directus instance(can be omitted if the provider is used)
• accessToken: the access token to use for authentication (can be omitted if the provider is used)
• asset: the asset representing the resource (string or object with an id property)
• download: force browser to download the asset (force the Content-Disposition header)
• directusTransform: an object with the Directus transform options or a preset key
• filename: the filename to use for the asset SEO
• render: a function (which receives an object with the url property) that provides the component to render

Example with custom transform

import{DirectusFile}from'react-directus';exportconstMyImage=({ imageId })=>(<DirectusFileasset={imageId}directusTransforms={{width: 200,height: 200}}render={({ url })=><imgsrc={url}/>}/>);

Example for downloading a file

import{DirectusFile}from'react-directus';exportconstMyImage=({ imageId })=>(<DirectusFileasset={imageId}downloadfilename="my-file-name.jpg"render={({ url, filename })=><ahref={url}download={filename}>Download</a>}/>);

📱 React Native

To make the project fully compatible with React Native you need to install the localstorage-polyfill package:

npm install localstorage-polyfill

Then import the module before any other import and force the storage mode "LocalStorage" in your Directus instance:

import'localstorage-polyfill';import{DirectusProvider}from'react-directus';import{View}from'react-native';exportdefaultfunctionApp({}){return(<DirectusProviderapiUrl='https://api.example.com'options={{storage: {mode: 'LocalStorage'}}}><View/></DirectusProvider>)}

In future releases, a solution using AsyncStorage or an encrypted secure storage option is planned.

❤️ Contributing

All types of contributions are encouraged and valued. See the Contributing guidelines, the community looks forward to your contributions!

📘 License

This project is released under the under terms of the ISC License.