Create a Custom Display

Custom displays allow you to create new ways of viewing field values inline throughout the App.

1. Setup the Boilerplate

Every display is a standalone "package" that contains at least a metadata file and a Vue component. We recommend using the following file structure:

src/
	index.js
	display.vue

src/index.js

import DisplayComponent from './display.vue';

export default {
	id: 'custom',
	name: 'Custom',
	description: 'This is my custom display!',
	icon: 'box',
	handler: DisplayComponent,
	types: ['string'],
};

id — The unique key for this display. It is good practice to scope proprietary displays with an author prefix.
name — The human-readable name for this display.
description — A short description (<80 characters) of this display shown in the App.
icon — An icon name from the material icon set, or the extended list of Directus custom icons.
handler — A function, or reference to your Vue component.
types — A CSV of supported types.

::: See the TypeScript definition for more info on what can go into this object. :::

src/display.vue

<template>
	<div>My Custom Display</div>
</template>

<script>
export default {};
</script>

The props you can use in an display are:

value — The value of the parent field.
interface - The interface of the parent field.
interface-options - The options for the parent field's interface.
type — The type of the parent field.
collection — The collection name of the parent field.
field — The key of the parent field.

Alternatively, you can specify a function for the handler. This allows you to make simple displays that don't need a full component rendered:

export default {
	id: 'custom',
	name: 'Custom',
	description: 'This is my custom display!',
	icon: 'box',
	handler: function (value) {
		return value.toLowerCase();
	},
	types: ['string'],
};

2. Install Dependencies and Configure the Buildchain

Set up a package.json file by running:

npm init -y

To be read by the Admin App, your custom display's Vue component must first be bundled into a single index.js file. We recommend bundling your code using Rollup. To install this and the other development dependencies, run this command:

npm i -D rollup rollup-plugin-commonjs rollup-plugin-node-resolve rollup-plugin-terser rollup-plugin-vue@5.0.0 @vue/compiler-sfc vue-template-compiler

You can then use the following Rollup configuration within rollup.config.js:

import { terser } from 'rollup-plugin-terser';
import resolve from 'rollup-plugin-node-resolve';
import commonjs from 'rollup-plugin-commonjs';
import vue from 'rollup-plugin-vue';

export default {
	input: 'src/index.js',
	output: {
		format: 'es',
		file: 'dist/index.js',
	},
	plugins: [terser(), resolve(), commonjs(), vue()],
};

3. Develop Your Custom Display

The display itself is simply a function or a Vue component, providing a blank canvas for creating anything you need.

4. Build and Deploy

To build the display for use within Directus, run:

npx rollup -c

Finally, move the output from your display's dist folder into your project's /extensions/displays folder. Keep in mind that the extensions directory is configurable within your env file, and may be located elsewhere.

3.5 KiB Raw Blame History