react-directus

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

🚀 Quick start

Install this library along with @directus/sdk:

npm install react-directus @directus/sdk

The <DirectusProvider> component makes the Directus JavaScript SDK available to any nested components that need to access it. Assuming that <App /> component is your root component:

import { App } from './App';
import { DirectusProvider } from 'react-directus';
import React from 'react';
import ReactDOM from 'react-dom';

ReactDOM.render(
  <DirectusProvider apiUrl="https://api.example.com">
    <App />
  </DirectusProvider>,
  document.getElementById('root')
);

You can optionally pass an apiOptions object to the provider, it will be passed to the client as the init parameter.

⚙️ The hook useDirectus

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

import React, { 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} />);
};

🧩 Components (so far...)

The hook exports a few components for working with Direcuts files file access. They are all configured for using the apiUrl specified in the provider. Hopefully, more will come in the future 🤗.

All components, when imported from react-directus directly (i.e. not imported using the hook useDirectus), can be used in a "standalone" way. It means that they are not bound to the apiUrl specified in the provider. In that case, they both accept an apiUrl prop.

<DirectusAsset>

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

• 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)
• render: a function (which receives an object with the url property) that provides the component to render

import React from 'react';
import { useDirectus } from 'react-directus';

export const TodoItem = ({ item }) => {
  const { DirectusAsset } = useDirectus();

  return (
    <div>
      <h1>Todo #{item.id}</h1>
      <DirectusAsset asset={item.attachment} download={true}
        render={({ asset, url }) => <a href={url}>{asset.filename_download}</a>} />
    </div>
  );
};

<DirectusImage>

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

• asset: the asset representing the resource (string or object with an id property)
• fit: fit of the thumbnail while always preserving the aspect ratio, can be any of the following options: cover, contain, inside or outside
• height: height of the thumbnail in pixels
• quality: quality of the thumbnail (1 to 100)
• width: width of the thumbnail in pixels
• render: a function (which receives an object with the url property) that provides the component to render

import React from 'react';
import { useDirectus } from 'react-directus';

export const TodoItem = ({ item }) => {
  const { DirectusImage } = useDirectus();

  return (
    <div>
      <h1>Todo #{item.id}</h1>
      <DirectusImage asset={item.image} fit="cover" quality="75"
        render={({ asset, url }) => <img src={url} alt={asset.title} />} />
    </div>
  );
};

❤️ Contributing

New features and bug-fix are always welcome! In order to contribute to this project, follow a few easy steps:

• Fork this repository, clone it on your machine and run npm install
• Open your local repository with Visual Studio Code and install all the suggested extensions
• Create a branch my-awesome-feature and commit to it
• Run npm run lint, npm run test and npm run build and verify that they complete without errors
• Push my-awesome-feature branch to GitHub and open a pull request
• Liked some of my work? Buy me a ☕ (or more likely 🍺)