diff --git a/docs/Fields/checkbox.mdx b/docs/Fields/checkbox.mdx
index d3a2270e60..1afe615dc0 100644
--- a/docs/Fields/checkbox.mdx
+++ b/docs/Fields/checkbox.mdx
@@ -15,6 +15,7 @@ order: 40
| **`name`** * | To be used as the property name when stored and retrieved from the database. |
| **`label`** | Used as a field label in the Admin panel and to name the generated GraphQL type. |
| **`validate`** | Provide a custom validation function that will be executed on both the Admin panel and the backend. [More](/docs/fields/overview#validation) |
+| **`index`** | Build a [MongoDB index](https://docs.mongodb.com/manual/indexes/) 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](/docs/authentication/config), include its data in the user JWT. |
| **`hooks`** | Provide field-based hooks to control logic for this field. [More](/docs/fields/overview#field-level-hooks) |
| **`access`** | Provide field-based access control to denote what users can see and do with this field's data. [More](/docs/fields/overview#field-level-access-control) |
diff --git a/docs/Fields/code.mdx b/docs/Fields/code.mdx
index 34a53cd942..611c2e1d67 100644
--- a/docs/Fields/code.mdx
+++ b/docs/Fields/code.mdx
@@ -17,6 +17,7 @@ This field uses `prismjs` for syntax highlighting and `react-simple-code-editor`
| **`name`** * | To be used as the property name when stored and retrieved from the database. |
| **`label`** | Used as a field label in the Admin panel and to name the generated GraphQL type. |
| **`unique`** | Enforce that each entry in the Collection has a unique value for this field. |
+| **`index`** | Build a [MongoDB index](https://docs.mongodb.com/manual/indexes/) for this field to produce faster queries. Set this field to `true` if your users will perform queries on this field's data often. |
| **`minLength`** | Used by the default validation function to ensure values are of a minimum character length. |
| **`maxLength`** | Used by the default validation function to ensure values are of a maximum character length. |
| **`validate`** | Provide a custom validation function that will be executed on both the Admin panel and the backend. [More](/docs/fields/overview#validation) |
diff --git a/docs/Fields/date.mdx b/docs/Fields/date.mdx
index f8d8a3f4d1..328bfd6e28 100644
--- a/docs/Fields/date.mdx
+++ b/docs/Fields/date.mdx
@@ -16,6 +16,7 @@ This field uses [`react-datepicker`](https://www.npmjs.com/package/react-datepic
| ---------------- | ----------- |
| **`name`** * | To be used as the property name when stored and retrieved from the database. |
| **`label`** | Used as a field label in the Admin panel and to name the generated GraphQL type. |
+| **`index`** | Build a [MongoDB index](https://docs.mongodb.com/manual/indexes/) for this field to produce faster queries. Set this field to `true` if your users will perform queries on this field's data often. |
| **`validate`** | Provide a custom validation function that will be executed on both the Admin panel and the backend. [More](/docs/fields/overview#validation) |
| **`saveToJWT`** | If this field is top-level and nested in a config supporting [Authentication](/docs/authentication/config), include its data in the user JWT. |
| **`hooks`** | Provide field-based hooks to control logic for this field. [More](/docs/fields/overview#field-level-hooks) |
diff --git a/docs/Fields/email.mdx b/docs/Fields/email.mdx
index 76592ea0e7..a9e7802dba 100644
--- a/docs/Fields/email.mdx
+++ b/docs/Fields/email.mdx
@@ -15,6 +15,7 @@ order: 70
| **`name`** * | To be used as the property name when stored and retrieved from the database. |
| **`label`** | Used as a field label in the Admin panel and to name the generated GraphQL type. |
| **`unique`** | Enforce that each entry in the Collection has a unique value for this field. |
+| **`index`** | Build a [MongoDB index](https://docs.mongodb.com/manual/indexes/) for this field to produce faster queries. Set this field to `true` if your users will perform queries on this field's data often. |
| **`validate`** | Provide a custom validation function that will be executed on both the Admin panel and the backend. [More](/docs/fields/overview#validation) |
| **`saveToJWT`** | If this field is top-level and nested in a config supporting [Authentication](/docs/authentication/config), include its data in the user JWT. |
| **`hooks`** | Provide field-based hooks to control logic for this field. [More](/docs/fields/overview#field-level-hooks) |
diff --git a/docs/Fields/number.mdx b/docs/Fields/number.mdx
index 8d83efdb03..af2cad233a 100644
--- a/docs/Fields/number.mdx
+++ b/docs/Fields/number.mdx
@@ -17,6 +17,7 @@ order: 90
| **`min`** | Minimum value accepted. Used in the default `validation` function. |
| **`max`** | Maximum value accepted. Used in the default `validation` function. |
| **`unique`** | Enforce that each entry in the Collection has a unique value for this field. |
+| **`index`** | Build a [MongoDB index](https://docs.mongodb.com/manual/indexes/) for this field to produce faster queries. Set this field to `true` if your users will perform queries on this field's data often. |
| **`validate`** | Provide a custom validation function that will be executed on both the Admin panel and the backend. [More](/docs/fields/overview#validation) |
| **`saveToJWT`** | If this field is top-level and nested in a config supporting [Authentication](/docs/authentication/config), include its data in the user JWT. |
| **`hooks`** | Provide field-based hooks to control logic for this field. [More](/docs/fields/overview#field-level-hooks) |
diff --git a/docs/Fields/overview.mdx b/docs/Fields/overview.mdx
index 91014ce36d..eed978892e 100644
--- a/docs/Fields/overview.mdx
+++ b/docs/Fields/overview.mdx
@@ -5,10 +5,10 @@ order: 10
---
- Fields are the building blocks of Payload. Collections and Globals both use Fields to define the shape of the data that they store. Payload offers a wide-array of field-types - both simple and complex.
+ Fields are the building blocks of Payload. Collections and Globals both use Fields to define the shape of the data that they store. Payload offers a wide-array of field types - both simple and complex.
-Fields are defined as an array on Collections and Globals via the `fields` key. They define the shape of the data that will be stored on Collections and Globals as well as automatically construct the corresponding Admin UI.
+Fields are defined as an array on Collections and Globals via the `fields` key. They define the shape of the data that will be stored as well as automatically construct the corresponding Admin UI.
The required `type` property on a field determines what values it can accept, how it is presented in the API, and how the field will be rendered in the admin interface.
@@ -45,28 +45,126 @@ const Pages = {
- [Relationship](/docs/fields/relationship) - assign relationships to other collections
- [Rich Text](/docs/fields/rich-text) - fully extensible Rich Text editor
- [Row](/docs/fields/row) - used for admin field layout, no effect on data shape
-- [Select](/docs/fields/select) - dropdown / picklist style based on `react-select`
+- [Select](/docs/fields/select) - dropdown / picklist style value selector
- [Text](/docs/fields/text) - simple text input
- [Textarea](/docs/fields/textarea) - allows a bit larger of a text editor
- [Upload](/docs/fields/upload) - allows local file and image upload
### Field-level hooks
-Briefly talk about field hooks and then link to the Field Hooks docs.
+One of the most powerful parts about Payload is its ability for you to define field-level hooks that can control the logic of your fields to a fine-grained level. for more information about how to define field hooks, [click here](/docs/hooks/config#field-hooks).
### Field-level access control
-Briefly talk about field access control and then link to the Field access control docs.
+In addition to being able to define access control on a document-level, you can define extremely granular permissions on a field by field level. For more information about field-level access control, [click here](/docs/access-control/config#fields).
-### Admin options
+### Admin config
-Go through admin options here.
+In addition to each field's base configuration, you can define specific traits and properties for fields that only have effect on how they are rendered in the Admin panel. The following properties are available for all fields within the `admin` property:
-- position
-- width
-- style
-- readOnly
-- disabled
-- condition
-- components
-- hidden
+**`condition`**
+
+You can programmatically show / hide fields based on what other fields are doing. [Click here](#conditional-logic) for more info.
+
+**`components`**
+
+All field components can be completely and easily swapped out for custom components that you define. [Click here](#custom-admin-components) for more info.
+
+**`position`**
+
+Specify if the field should be rendered in the main editable area (leave the field undefined) or the sidebar, by defining `position: 'sidebar'`.
+
+**`width`**
+
+Restrict the width of a field. you can pass any string-based value here, be it pixels, percentages, etc. This property is especially useful when fields are nested within a `Row` type where they can be organized horizontally.
+
+**`readOnly`**
+
+Setting a field to `readOnly` has no effect on the API whatsoever but disables the admin component's editability to prevent editors from modifying the field's value.
+
+**`disabled`**
+
+If a field is `disabled`, it is completely omitted from the Admin panel.
+
+**`hidden`**
+
+Setting a field's `hidden` property on its `admin` config will transform it into a `hidden` input type. Its value will still submit with the Admin panel's requests, but the field itself will not be visible to editors.
+
+### Conditional logic
+
+You can show and hide fields based on what other fields are doing by utilizing conditional logic on a field by field basis. The `condition` property on a field's admin config accepts a function which takes two arguments:
+
+- `data` - the entire document's data that is currently being edited
+- `siblingData` - only the fields that are direct siblings to the field with the condition
+
+The `condition` function should return a boolean that will control if the field should be displayed or not.
+
+**Example:**
+
+```js
+{
+ fields: [
+ {
+ name: 'enableGreeting',
+ type: 'checkbox',
+ defaultValue: false,
+ },
+ {
+ name: 'greeting',
+ type: 'text',
+ admin: {
+ // highlight-start
+ condition: (data, siblingData) => {
+ if (data.enableGreeting) {
+ return true;
+ } else {
+ return false;
+ }
+ }
+ // highlight-end
+ }
+ }
+ ]
+}
+```
+
+### Custom components
+
+All Payload fields support the ability to swap in your own React components with ease. So, for example, instead of rendering a default Text input, you might need to render a color picker that provides the editor with a custom color picker interface to restrict the data entered to colors only.
+
+**Custom components will automatically be provided with all props that the default component would accept.**
+
+
+ Tip:
+ Don't see a built-in field type that you need? Build it! Using a combination of custom validation and custom components, you can override the entirety of how a component functions within the admin panel and effectively create your own field type.
+
+
+Fields support the following custom components:
+
+**`Filter`**
+
+Passing a `Filter` component will override the text input that is presented in the `List` view when a user is filtering documents by the customized field.
+
+**`Cell`**
+
+This component will be used in the `List` view's table to represent a table-based preview of the data stored in the field.
+
+**`Field`**
+
+Specifying this component will swap out the field itself within all `Edit` views. You will be responsible for sending and receiving the field's `value` from the form itself.
+
+Example:
+```js
+import { useFieldType } from 'payload/components/forms';
+
+const CustomTextField = ({ path }) => {
+ const { value, setValue } = useFieldType({ path });
+
+ return (
+ setValue(e.target.value)}
+ value={value}
+ />
+ )
+}
+```
diff --git a/docs/Fields/radio.mdx b/docs/Fields/radio.mdx
index 46cf49fdb8..96f86c8c2e 100644
--- a/docs/Fields/radio.mdx
+++ b/docs/Fields/radio.mdx
@@ -16,6 +16,7 @@ order: 100
| **`options`** * | Array of options to allow the field to store. Can either be an array of strings, or an array of objects containing an `option` string and a `value` string. |
| **`label`** | Used as a field label in the Admin panel and to name the generated GraphQL type. |
| **`validate`** | Provide a custom validation function that will be executed on both the Admin panel and the backend. [More](/docs/fields/overview#validation) |
+| **`index`** | Build a [MongoDB index](https://docs.mongodb.com/manual/indexes/) 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](/docs/authentication/config), include its data in the user JWT. |
| **`hooks`** | Provide field-based hooks to control logic for this field. [More](/docs/fields/overview#field-level-hooks) |
| **`access`** | Provide field-based access control to denote what users can see and do with this field's data. [More](/docs/fields/overview#field-level-access-control) |
diff --git a/docs/Fields/relationship.mdx b/docs/Fields/relationship.mdx
index 8147f3da08..0eb1242cdd 100644
--- a/docs/Fields/relationship.mdx
+++ b/docs/Fields/relationship.mdx
@@ -24,6 +24,7 @@ order: 110
| **`label`** | Used as a field label in the Admin panel and to name the generated GraphQL type. |
| **`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](/docs/fields/overview#validation) |
+| **`index`** | Build a [MongoDB index](https://docs.mongodb.com/manual/indexes/) 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](/docs/authentication/config), include its data in the user JWT. |
| **`hooks`** | Provide field-based hooks to control logic for this field. [More](/docs/fields/overview#field-level-hooks) |
| **`access`** | Provide field-based access control to denote what users can see and do with this field's data. [More](/docs/fields/overview#field-level-access-control) |
diff --git a/docs/Fields/select.mdx b/docs/Fields/select.mdx
index e774783aa3..ee882190ad 100644
--- a/docs/Fields/select.mdx
+++ b/docs/Fields/select.mdx
@@ -18,6 +18,7 @@ order: 140
| **`label`** | Used as a field label in the Admin panel and to name the generated GraphQL type. |
| **`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](/docs/fields/overview#validation) |
+| **`index`** | Build a [MongoDB index](https://docs.mongodb.com/manual/indexes/) 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](/docs/authentication/config), include its data in the user JWT. |
| **`hooks`** | Provide field-based hooks to control logic for this field. [More](/docs/fields/overview#field-level-hooks) |
| **`access`** | Provide field-based access control to denote what users can see and do with this field's data. [More](/docs/fields/overview#field-level-access-control) |
diff --git a/docs/Fields/text.mdx b/docs/Fields/text.mdx
index bd787520a1..b75c6af1f6 100644
--- a/docs/Fields/text.mdx
+++ b/docs/Fields/text.mdx
@@ -18,6 +18,7 @@ order: 150
| **`minLength`** | Used by the default validation function to ensure values are of a minimum character length. |
| **`maxLength`** | Used by the default validation function to ensure values are of a maximum character length. |
| **`validate`** | Provide a custom validation function that will be executed on both the Admin panel and the backend. [More](/docs/fields/overview#validation) |
+| **`index`** | Build a [MongoDB index](https://docs.mongodb.com/manual/indexes/) 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](/docs/authentication/config), include its data in the user JWT. |
| **`hooks`** | Provide field-based hooks to control logic for this field. [More](/docs/fields/overview#field-level-hooks) |
| **`access`** | Provide field-based access control to denote what users can see and do with this field's data. [More](/docs/fields/overview#field-level-access-control) |
diff --git a/docs/Fields/textarea.mdx b/docs/Fields/textarea.mdx
index e8044ffcca..085485d5a0 100644
--- a/docs/Fields/textarea.mdx
+++ b/docs/Fields/textarea.mdx
@@ -18,6 +18,7 @@ order: 160
| **`minLength`** | Used by the default validation function to ensure values are of a minimum character length. |
| **`maxLength`** | Used by the default validation function to ensure values are of a maximum character length. |
| **`validate`** | Provide a custom validation function that will be executed on both the Admin panel and the backend. [More](/docs/fields/overview#validation) |
+| **`index`** | Build a [MongoDB index](https://docs.mongodb.com/manual/indexes/) 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](/docs/authentication/config), include its data in the user JWT. |
| **`hooks`** | Provide field-based hooks to control logic for this field. [More](/docs/fields/overview#field-level-hooks) |
| **`access`** | Provide field-based access control to denote what users can see and do with this field's data. [More](/docs/fields/overview#field-level-access-control) |
diff --git a/docs/Fields/upload.mdx b/docs/Fields/upload.mdx
index 6aebcd72d5..dbec83fc3f 100644
--- a/docs/Fields/upload.mdx
+++ b/docs/Fields/upload.mdx
@@ -29,6 +29,7 @@ order: 170
| **`label`** | Used as a field label in the Admin panel and to name the generated GraphQL type. |
| **`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](/docs/fields/overview#validation) |
+| **`index`** | Build a [MongoDB index](https://docs.mongodb.com/manual/indexes/) 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](/docs/authentication/config), include its data in the user JWT. |
| **`hooks`** | Provide field-based hooks to control logic for this field. [More](/docs/fields/overview#field-level-hooks) |
| **`access`** | Provide field-based access control to denote what users can see and do with this field's data. [More](/docs/fields/overview#field-level-access-control) |