Select Field
The Select Field provides a dropdown-style interface for choosing options from a predefined list as an enumeration.
Admin Panel screenshot of a Select field
To add a Select Field, set the type to select in your Field Config:
1
import type { Field } from 'payload'
2
3
export const MySelectField: Field = {
4
// ...
5
type: 'select',
6
options: [
7
// ...
8
]
9
}
Config Options
| Option | Description |
|---|---|
name * | To be used as the property name when stored and retrieved from the database. More |
options * | Array of options to allow the field to store. Can either be an array of strings, or an array of objects containing a label string and a value string. |
hasMany | Boolean when, if set to true, allows this field to have many selections instead of only one. |
label | Text used as a field label in the Admin Panel or an object with keys for each language. |
unique | Enforce that each entry in the Collection has a unique value for this field. |
validate | Provide a custom validation function that will be executed on both the Admin Panel and the backend. More |
index | Build an index for this field to produce faster queries. Set this field to true if your users will perform queries on this field's data often. |
saveToJWT | If this field is top-level and nested in a config supporting Authentication, include its data in the user JWT. |
hooks | Provide Field Hooks to control logic for this field. More details. |
access | Provide Field Access Control to denote what users can see and do with this field's data. More details. |
hidden | Restrict this field's visibility from all APIs entirely. Will still be saved to the database, but will not appear in any API or the Admin Panel. |
defaultValue | Provide data to be used for this field's default value. More |
localized | Enable localization for this field. Requires localization to be enabled in the Base config. |
required | Require this field to have a value. |
admin | Admin-specific configuration. See the default field admin config for more details. |
custom | Extension point for adding custom data (e.g. for plugins) |
enumName | Custom enum name for this field when using SQL Database Adapter (Postgres). Auto-generated from name if not defined. |
dbName | Custom table name (if hasMany set to true) for this field when using SQL Database Adapter (Postgres). Auto-generated from name if not defined. |
typescriptSchema | Override field type generation with providing a JSON schema |
virtual | Provide true to disable field in the database. See Virtual Fields |
* An asterisk denotes that a property is required.
Admin Options
The customize the appearance and behavior of the Select Field in the Admin Panel, you can use the admin option:
1
import type { Field } from 'payload'
2
3
export const MySelectField: Field = {
4
// ...
5
admin: {
6
// ...
7
},
8
}
The Select Field inherits all of the default options from the base Field Admin Config, plus the following additional options:
| Property | Description |
|---|---|
isClearable | Set to true if you'd like this field to be clearable within the Admin UI. |
isSortable | Set to true if you'd like this field to be sortable within the Admin UI using drag and drop. (Only works when hasMany is set to true) |
Example
collections/ExampleCollection.ts
1
import type { CollectionConfig } from 'payload'
2
3
export const ExampleCollection: CollectionConfig = {
4
slug: 'example-collection',
5
fields: [
6
{
7
name: 'selectedFeatures', // required
8
type: 'select', // required
9
hasMany: true,
10
admin: {
11
isClearable: true,
12
isSortable: true, // use mouse to drag and drop different values, and sort them according to your choice
13
},
14
options: [
15
{
16
label: 'Metallic Paint',
17
value: 'metallic_paint',
18
},
19
{
20
label: 'Alloy Wheels',
21
value: 'alloy_wheels',
22
},
23
{
24
label: 'Carbon Fiber Dashboard',
25
value: 'carbon_fiber_dashboard',
26
},
27
],
28
},
29
],
30
}
Customization
The Select field UI component can be customized by providing a custom React component to the components object in the Base config.
1
export const CustomSelectField: Field = {
2
name: 'customSelectField',
3
type: 'select', // or 'text' if you have dynamic options
4
admin: {
5
components: {
6
Field: CustomSelectComponent({
7
options: [
8
{
9
label: 'Option 1',
10
value: '1',
11
},
12
{
13
label: 'Option 2',
14
value: '2',
15
},
16
],
17
}),
18
},
19
},
20
}
You can import the existing Select component directly from Payload, then extend and customize it as needed.
1
import * as React from 'react';
2
import { SelectInput, useAuth, useField } from '@payloadcms/ui';
3
4
type CustomSelectProps = {
5
path: string;
6
options: {
7
label: string;
8
value: string;
9
}[];
10
}
11
12
export const CustomSelectComponent: React.FC<CustomSelectProps> = ({ path, options }) => {
13
const { value, setValue } = useField<string>({ path })
14
const { user } = useAuth()
15
16
const adjustedOptions = options.filter((option) => {
17
/*
18
A common use case for a custom select
19
is to show different options based on
20
the current user's role.
21
*/
22
return option;
23
});
24
25
return (
26
<div>
27
<label className="field-label">
28
Custom Select
29
</label>
30
<SelectInput
31
path={path}
32
name={path}
33
options={adjustedOptions}
34
value={value}
35
onChange={(e) => setValue(e.value)}
36
/>
37
</div>
38
)
39
}
If you are looking to create a dynamic select field, the following tutorial will walk you through the process of creating a custom select field that fetches its options from an external API.
If you want to learn more about custom components check out the Admin > Custom Component docs.
Next