Directus Docs

# Custom Layouts

Custom Layouts allow for building new ways to view or interact with Items via the Collection Detail pages. Learn more about Layouts.

# 1. Setup the Boilerplate

Every layout 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
	layout.vue

# src/index.js

import { ref } from 'vue';
import LayoutComponent from './layout.vue';

export default {
	id: 'custom',
	name: 'Custom',
	icon: 'box',
	component: LayoutComponent,
	slots: {
		options: () => null,
		sidebar: () => null,
		actions: () => null,
	},
	setup() {
		const name = ref('Custom Layout');

		return { name };
	},
};
  • id — The unique key for this layout. It is good practice to scope proprietary layouts with an author prefix.
  • name — The human-readable name for this layout.
  • icon — An icon name from the material icon set, or the extended list of Directus custom icons.
  • component — A reference to your Vue component.

TypeScript

See the TypeScript definition (opens new window) for more info on what can go into this object.

# src/layout.vue

<template>
	<div>
		<p>Name: {{ name }}</p>
		<p>Collection: {{ collection }}</p>
	</div>
</template>

<script>
export default {
	inheritAttrs: false,
	props: {
		collection: {
			type: String,
			required: true,
		},
		name: {
			type: String,
			required: true,
		},
	},
};
</script>

The props you can use in an layout are:

  • collection — The current collection's name.
  • selection (sync) - Any currently selected items.
  • layout-options (sync) - The user's current saved layout options.
  • layout-query (sync) - The user's layout query parameters. (eg: sort, limit, etc)
  • filters (sync) - The user's currently active filters.
  • search-query (sync) - The user's current search query.

# 2. Install Dependencies

Set up a package.json file by running:

npm init -y

To be read by the Admin App, your custom layouts's Vue component must first be bundled into a single index.js file. We recommend bundling your code using the directus-extension CLI from our @directus/extensions-sdk package. The CLI internally uses a Rollup configuration tailored specifically to bundling Directus extensions. To install the Extension SDK, run this command:

npm i -D @directus/extensions-sdk

For the directus-extension CLI to recognize the extension type, the input path and the output path, add this field to the root of the package.json file:

"directus:extension": {
	"type": "layout",
	"path": "dist/index.js",
	"source": "src/index.js",
	"host": "^9.0.0-rc.87",
	"hidden": false
}

# 3. Develop Your Custom Layout

The layout itself is simply a Vue component, which provides an blank canvas for creating anything you need.

# 4. Build and Deploy

To build the layout for use within Directus, run:

npx directus-extension build

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

← Migrations →