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';

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.

<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';

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.