directus/docs/guides/collections.md

Collections

Collections are containers for specific groupings of Items. Each collection represents a table in your database. Learn more about Collections.

Creating a Collection

1. Navigate to Settings > Data Model
2. Click the Create Collection action button in the header
3. Enter a unique Collection Name, keeping in mind that this is entered as a key that determines the database table name, and is then presented in the App using the internal Title Formatter.
4. Optional: Configure the collection's Primary Key name and type.
   • Auto-Incremented Integer
   • Generated UUID
   • Manually Entered String
5. Optional: Enable and rename any desired System Fields.
   • Status
   • Sort
   • Created On
   • Created By
   • Updated On
   • Updated By
6. Click the Finish Setup button

::: danger Immutable Keys

The collection name, primary key name/type, and system field names can not be modified after the collection is created.

:::

::: tip Database Tables

Keep in mind that a Directus Collection is just a database table. Therefore you can import or create a table directly in the database, and it will automatically appear within Directus. The first time you manage that table, a directus_collections record will be created with default values.

:::

Configuring a Collection

1. Navigate to Settings > Data Model > [Collection Name]
2. Configure the following settings:
   • Collection Name — This is the key for the collection. It can not be modified, but you can override it with Translations (see field below).
   • Icon — The icon used throughout the App when referencing this collection
   • Note — A helpful note that explains the collection's purpose
   • Display Template — A Field Template that creates dynamic titles for the collection's items
   • Hidden — Toggles if the collection should be globally hidden. Keep in mind that Admin roles can always see all collections.
   • Singleton — For collections that will only contain a single item (eg: an "About Us" form), the Collection Detail will be bypassed, and users are taken directly to the Item Detail page.
   • Translation — Allows translating the collection name into different languages. These Schema Translations are important for multilingual projects. You can also "translate" a collection name into the default language — helpful for renaming technical table names.
3. Create and configure any fields within this Collection.
   • Creating a Field
   • Updating a Field
   • Deleting a Field
   • Duplicating a Field
   • Changing Field Order & Layout
4. Optional: Configure the Archive and Sort options below.

Archive

The archive feature allows you to enable the collection with a custom soft-delete option. Soft-delete allows users to remove items from the App, but maintains the actual database record for easy recovery.

• Archive Field — The field that holds the archive value
• Archive App Filter — Allows users to view archived items
• Archive Value — The value saved in the Archive Field when archived
• Unarchive Value — The value saved in the Archive Field when unarchived

::: warning API Responses

Items that have been archived are still returned normally via the API. It is up to you to filter them out as needed.

:::

::: tip Automatic Setup

When creating a new Collection, you have the option of creating an optional "Status" field. If you choose to include this field, the collection's archive settings will automatically be configured for you.

:::

Sort

The sort feature enables manual drag-and-drop item reordering within the Directus App. This is typically shown on the Collection Detail page/modal, and can also be used for sorting items within a Junction Table.

To configure manual sorting for a collection:

1. Navigate to Settings > Data Model > [Collection Name]
2. Create a field with the Integer type
   • Optional: Set the field to be Hidden
3. Select the field you just created in the Sort Field dropdown

::: tip Automatic Setup

When creating a new Collection, you have the option of creating an optional "Sort" field. If you choose to include this field, the collection's sort settings will automatically be configured for you.

:::

::: tip Interface Sorting

To configure manual sorting within an Interface (eg: M2M, O2M, or M2A), configure as above, but also set the Sort Field on the field's Relationship pane.

:::

Renaming a Collection

While you can not change the Key of a collection via Directus (as of now), you can change its Name and translations.

1. Navigate to Settings > Data Model > [Collection Name]
2. Click the Add New button under Collection Name Translations
3. Choose the desired Language (your primary language for "renaming")
4. Enter a Translation
5. Click the Save button

::: tip Special Casing

If you are trying to update the specific casing (uppercase/lowercase) for a word (eg: Dna to DNA) you will want to add the edge-case to the Format Title package. If you feel the case passes our 80/20 rule you should submit a Pull Request to the codebase, otherwise you can update this in your instance.

:::

Deleting a Collection

1. Navigate to Settings > Data Model > [Collection Name]
2. Click the red Delete Collection action button in the header
3. Confirm this decision by clicking Delete in the dialog

::: danger Irreversible Change

This action is permanent and can not be undone. Please proceed with caution.

:::

Adjusting a Collection Layout

1. Navigate to Collections > [Collection Name]
2. Click "Layout Options" in the Page Sidebar
3. Configure the Layout Options as desired

::: tip User Preferences

Any changes made to the Collection Layout Options, page filters, search queries, and advanced filters, are instantly saved to your user preferences. This means that your experience will be the same when logging later, even if using a different device.

:::