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 hookuseDirectus
), can be used in a "standalone" way. It means that they are not bound to theapiUrl
specified in the provider. In that case, they both accept anapiUrl
prop.
<DirectusAsset>
Computes the URL of the given resource asset
, rendering it using the render
prop:
-
asset
: the asset representing the resource (string
orobject
with anid
property) -
download
: force browser to download the asset (force theContent-Disposition
header) -
render
: a function (which receives an object with theurl
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
orobject
with anid
property) -
fit
: fit of the thumbnail while always preserving the aspect ratio, can be any of the following options:cover
,contain
,inside
oroutside
-
height
: height of the thumbnail in pixels -
quality
: quality of the thumbnail (1
to100
) -
width
: width of the thumbnail in pixels -
render
: a function (which receives an object with theurl
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
andnpm 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🍺 )