Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/gremo/react-directus
A set of React components and utilities for Directus Headless CMS
https://github.com/gremo/react-directus
directus react
Last synced: 20 days ago
JSON representation
A set of React components and utilities for Directus Headless CMS
- Host: GitHub
- URL: https://github.com/gremo/react-directus
- Owner: gremo
- License: isc
- Created: 2021-05-03T23:12:17.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2024-11-18T19:17:13.000Z (25 days ago)
- Last Synced: 2024-11-18T20:28:16.249Z (25 days ago)
- Topics: directus, react
- Language: TypeScript
- Homepage:
- Size: 1.95 MB
- Stars: 118
- Watchers: 3
- Forks: 14
- Open Issues: 13
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
Awesome Lists containing this project
- awesome-directus - react-directus - A set of React components and utilities for Directus Headless CMS. (Integration / Community)
README
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.
```bash
npm install react-directus @directus/sdk@^10
```
The `` component makes the [Directus JavaScript SDK](https://docs.directus.io/reference/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](https://docs.directus.io/reference/sdk/#reference)
- `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
```jsx
import { App } from './App';
import { DirectusProvider } from 'react-directus';
import { createRoot } from 'react-dom/client';
const root = createRoot(document.getElementById('root'));
root.render(
);
```
With **TypeScript**, you can use the optional generic collection type for Directus, as described in the [Directus TypeScript documentation](https://docs.directus.io/reference/old-sdk.html#typescript):
```jsx
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(
apiUrl="https://api.example.com" options={{}}>
);
```
## ⚙️ Hooks
### `useDirectus`
After adding the provider, you can access the configured client anywhere in the app, using the `useDirectus` hook:
```jsx
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 => );
};
```
### `useDirectusAuth`
The `useDirectusAuth` hook provides a few methods for working with the [Directus Authentication API](https://docs.directus.io/reference/old-sdk.html#authentication):
- `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`
```jsx
import { useDirectusAuth } from 'react-directus';
import { FormEvent } from 'react';
const Login = () => {
const { login } = useDirectusAuth();
const handleSubmit = (e: FormEvent) => {
e.preventDefault();
const { email, password } = e.currentTarget.elements;
login(email.value, password.value).catch(err => {
console.error(err);
});
};
return (
Login
);
};
export default Login;
```
## 🧩 Components (so far...)
This package contains a component for working with Direcuts [files](https://docs.directus.io/reference/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](https://docs.directus.io/reference/files/#transform) options or a preset key
- `filename`: the filename to use for the asset [SEO](https://docs.directus.io/reference/files/#accessing-a-file)
- `render`: a function (which receives an object with the `url` property) that provides the component to render
#### Example with custom transform
```jsx
import { DirectusFile } from 'react-directus';
export const MyImage = ({ imageId }) => (
}
/>
);
```
#### Example for downloading a file
```jsx
import { DirectusFile } from 'react-directus';
export const MyImage = ({ imageId }) => (
Download}
/>
);
```
## 📱 React Native
To make the project fully compatible with React Native you need to install the [localstorage-polyfill](https://www.npmjs.com/package/localstorage-polyfill) package:
```bash
npm install localstorage-polyfill
```
Then import the module **before any other import** and force the storage mode "LocalStorage" in your Directus instance:
```jsx
import 'localstorage-polyfill';
import { DirectusProvider } from 'react-directus';
import { View } from 'react-native';
export default function App({}) {
return (
)
}
```
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](CONTRIBUTING.md) guidelines, the community looks forward to your contributions!
## 📘 License
This project is released under the under terms of the [ISC License](LICENSE).