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 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';
const root = createRoot(document.getElementById('root'));
root.render(
  <DirectusProvider apiUrl="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';
import MyCollections from './types';
const root = 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'
export const TodoList = () => {
  // Get the Directus SDK object
  const { directus } = useDirectus();
  const [todos, setTodos] = useState([]);
useEffect(() => {
    const fetchTodos = async () => {
      const todos = (await directus.items('todos').readMany()).data;
      setTodos(todos);
    };
fetchTodos();
  }, [directus]);
return todos.map(item => <TodoItem key={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';
const Login = () => {
  const { login } = useDirectusAuth();
const handleSubmit = (e: FormEvent<HTMLFormElement>) => {
    e.preventDefault();
const { email, password } = e.currentTarget.elements;
    login(email.value, password.value).catch(err => {
      console.error(err);
    });
  };
return (
    <form onSubmit={handleSubmit}>
      <input type='email' name='email' />
      <input type='password' name='password' />
      <button type='submit'>Login</button>
    </form>
  );
};
export default Login;

🧩 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.

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';
export const MyImage = ({ imageId }) => (
  <DirectusFile
    asset={imageId}
    directusTransforms={{ width: 200, height: 200 }}
    render={({ url }) => <img src={url} />}
  />
);

Example for downloading a file

import { DirectusFile } from 'react-directus';
export const MyImage = ({ imageId }) => (
  <DirectusFile
    asset={imageId}
    download
    filename="my-file-name.jpg"
    render={({ url, filename }) => <a href={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';
export default function App({}) {
    return (
        <DirectusProvider
            apiUrl='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.