In this guide, we’re going to go over how to use collections in Payload CMS. Let’s dive in.
A collection is a group of documents that share common structure. You can have as many collections as you need for a project, and each collection you create will take up its own space in your admin dashboard. Each document you create is stored in your database using the fields you define. You can learn more about what fields are available to you by reading my guides on data, presentational, and relationship fields.
What you define in each collection automatically generates Local, REST, and GraphQL API for you to query your database to render data on your frontend. These APIs are represented as JSON in the API window in each of your individual collection item’s view.
We covered how to add collections to your Payload config file in my Step-by-Step Guide to Configuring PayloadCMS Config Settings guide. But it’s best practice to create your collections in a separate file and then import them into your config.
So how do you define a collection? First, create a new file to create your collection. I typically store these collection files in a collections directory, but you don’t need to do that. So, if I want to create a new Posts collection to store my blog posts, I can do that by creating a new directory in my collections folder called Posts and then add a TypeScript file called config.
There are a few things you need to do to get your Collection going. First, you need to import the CollectionConfig type from payload. This lets you stay within the bounds of what PayloadCMS expects you to provide when creating a collection.
Next, you’ll export a constant called the name of the file, in our case "Posts," and assign the CollectionConfig to it. Set it equal to an object that contains a slug and an array of fields. The slug can be whatever you want it to be, but it’s recommended that you set it to be the same name as the collection in order to prevent confusion to yourself and others.
You can also include as many fields as you’d like to in your collection as long as they stay within the fields array. There are no required fields, but fields are required to create a collection, so feel free to experiment with different fields to build your own collection. For a blog, we might include a title, slug, and content field to create the collection we need.
From there, you can go to your payload configuration file and import your newly created Collection to your collections option.
Slug and the fields options are required, but you have some additional options available to you when creating a collection. Some common ones include admin, access, auth, defaultSort, hooks, labels, upload, and defaultPopulate.
Admin
Collections, just like fields, have many ways to configure your collection at the admin level. There are several admin options you will use when creating collections. Some common ones include group, useAsTitle, and description.
Group
The group option allows you to organize your admin panel by grouping links together. For example, if you have a category and a topic collection, you could group these together in a “meta” group to keep them organized. To show you how that done, here I have two collections, and I’ll set each of their group setting to “meta.”
You can also set this option to false to hide it from the navigation, but you’re still able to access the routes on the frontend.
useAsTitle
The useAsTitle option is used to set what you want your title to be set as for the document throughout the admin panel. This includes any relationship field you have as well. This must be a top level field, so it cannot be based on anything within a group, array, or anything that takes the field down a level. You also can’t use any field that is set as a virtual field as a title.
If nothing is defined, the id will be used as the title.
Description
The description option is used to set a text description under the Collection label. You can use this space to describe what the collection is about to give editors or yourself more information about the collection.
You can also use admin.components.Description to render a React component, but we’ll cover that in a separate guide.
Access
You can set the access option to provide finetuned control over who can access this collection. You have the option to set read, create, update, and delete permissions, which all accept either a boolean or a function returning a boolean. We will dive deeper into access controls in a later guide, but for now we’ll set all but delete to true.
Auth
Use the auth option to select the collection for authentication. For example, our Users collection is what’s used for authentication. This field doesn’t need much more explanation than that, as it can only be true or false and is false by default.
defaultSort
The defaultSort option is used to set how you want to sort your Collection items in the list view. This needs to be a top-level field, so it can’t be a field in a group or any other kind of field that takes the field down a level.
This sorts by ascending by default. If you’d like to sort by descending, you can start this option with a minus symbol to sort in descending order. If you use an array of strings, you can sort by multiple fields, with the first array item being sorted first.
Labels
If you want to use a different name for your collection than your slug, you can set this by using the label option. A great use case for this is with our Posts example. If we want to query this collection using our posts slug but we want to call these Blogs in your admin dashboard, we can do that by setting the label option to an object with a plural and singular option. These are case sensitive, so be sure that you type these in exactly like you want to see them in the dashboard.
Upload
If you want your collection to support file uploads, you will need to either use upload: true, or set upload with an object with some more options. This is extremely flexible and can be used to convert files on upload, restrict accepted mime types, and allows you to handle how thumbnails are presented.
formatOptions
When you upload files, you can use formatOptions to automatically convert files into other formats. If you want all your images to be converted to webp, for example, you can do that by including formatOptions.format and set it to ‘webp.’ This uses the Sharp image library to convert your file upon upload.
mimeTypes
The mimeTypes option allows you to specify what types of documents your upload field allows. This expects an array of strings that acts as a whitelist of available types. For example, if you want to include only images, you can use “image/*”. If you want only webp and png images to be allowed, you can use [“image/webp”, “image/png”] You can look up lists of available mimeTypes to build out exactly what you want your upload field to accept.
This is not limited to images, either. You can also set restrictions to only allow PDFs or other documents, all by just setting what mimeTypes to accept.
adminThumbnail
You can set adminThumbnail to determine how images are shown as thumbnails in the admin dashboard. You can either use a string to tell your collection how to handle the thumbnail or you can set it as a function.
When you use a string, you can use ‘small’ for example to set your thumbnail to a small imageSize that you set in the imageSizes array.
Or, as I prefer, you can set the thumbnail using a function which takes a document as an argument. You can then use your own media bucket and programmatically create a path to the file to then be used in your admin dashboard.
You can set displayPreview to false if you don’t want to include a preview of the uploaded file in the upload process. This can be helpful for when you want to skip the preview for documents but not images. You’re able to set this as a global option in the upload configuration, but you’re still able to override it locally if you want to use the same upload collection for multiple file types. For example, for one upload field, you may want to only accept documents that don’t need to be previewed before uploading. For another upload field, you may want to only accept images that do need to be previewed. You can set this using the displayPreview option.
defaultPopulate
The defaultPopulate collection configuration option is incredibly helpful when you want to reduce how much JSON you’re sending from relationship and upload fields. Instead of sending the entire document every time you query it, you can select a few fields to be used on the frontend using defaultPopulate.
For example, say you only want to send the slug and name field from our Users collection. You can do that by setting defaultPopulate.slug and .name to true. This will ensure that only these fields are populated when used in relationship with another collection.
If you want to populate more than these fields in some cases, you can use populate in the local API to show those fields.
Using these options should help you optimize how much data you’re sending.
Final Thoughts
Collections are the structure of your site. You’ll typically have collections for pages, posts, media, and much more. When creating a collection, be sure to have the final design in mind so you know what fields and options you need in order to create your final project.
