diff --git a/docs/fields/array.mdx b/docs/fields/array.mdx index 890690e3a..a3dab6975 100644 --- a/docs/fields/array.mdx +++ b/docs/fields/array.mdx @@ -2,14 +2,17 @@ title: Array Field label: Array order: 20 -desc: Array fields are intended for sets of repeating fields, that you define. Learn how to use array fields, see examples and options. +desc: Array Fields are intended for sets of repeating fields, that you define. Learn how to use Array Fields, see examples and options. keywords: array, fields, config, configuration, documentation, Content Management System, cms, headless, javascript, node, react, nextjs --- - - The Array field type is used when you need to have a set of "repeating" fields. It stores an array - of objects containing the fields that you define. Its uses can be simple or highly complex. - +The Array Field is used when you need to have a set of "repeating" [Fields](./overview). It stores an array of objects containing fields that you define. These fields can be of any type, including other arrays to achieve infinitely nested structures. + +Arrays are useful for many different types of content from simple to complex, such as: + +- A "slider" with an image ([upload field](/docs/fields/upload)) and a caption ([text field](/docs/fields/text)) +- Navigational structures where editors can specify nav items containing pages ([relationship field](/docs/fields/relationship)), an "open in new tab" [checkbox field](/docs/fields/checkbox) +- Event agenda "timeslots" where you need to specify start & end time ([date field](/docs/fields/date)), label ([text field](/docs/fields/text)), and Learn More page [relationship](/docs/fields/relationship) -**Example uses:** +To create an Array Field, set the `type` to `array` in your [Field Config](./overview): -- A "slider" with an image ([upload field](/docs/fields/upload)) and a caption ([text field](/docs/fields/text)) -- Navigational structures where editors can specify nav items containing pages ([relationship field](/docs/fields/relationship)), an "open in new tab" [checkbox field](/docs/fields/checkbox) -- Event agenda "timeslots" where you need to specify start & end time ([date field](/docs/fields/date)), label ([text field](/docs/fields/text)), and Learn More page [relationship](/docs/fields/relationship) +```ts +import type { Field } from 'payload/types' -## Config +export const MyArrayField: Field = { + // ... + // highlight-start + type: 'array', + fields: [ + // ... + ], + // highlight-end +} +``` + +## Config Options | Option | Description | | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -42,7 +55,7 @@ keywords: array, fields, config, configuration, documentation, Content Managemen | **`localized`** | Enable localization for this field. Requires [localization to be enabled](/docs/configuration/localization) in the Base config. If enabled, a separate, localized set of all data within this Array will be kept, so there is no need to specify each nested field as `localized`. | | **`required`** | Require this field to have a value. | | **`labels`** | Customize the row labels appearing in the Admin dashboard. | -| **`admin`** | Admin-specific configuration. See below for [more detail](#admin-config). | +| **`admin`** | Admin-specific configuration. [More details](#admin-options). | | **`custom`** | Extension point for adding custom data (e.g. for plugins) | | **`interfaceName`** | Create a top level, reusable [Typescript interface](/docs/typescript/generating-types#custom-field-interfaces) & [GraphQL type](/docs/graphql/graphql-schema#custom-field-schemas). | | **`dbName`** | Custom table name for the field when using SQL Database Adapter ([Postgres](/docs/database/postgres)). Auto-generated from name if not defined. | @@ -50,9 +63,22 @@ keywords: array, fields, config, configuration, documentation, Content Managemen _\* An asterisk denotes that a property is required._ -## Admin Config +## Admin Options -In addition to the default [field admin config](/docs/fields/overview#admin-config), you can adjust the following properties: +The customize the appearance and behavior of the Array Field in the [Admin Panel](../admin/overview), you can use the `admin` option: + +```ts +import type { Field } from 'payload/types' + +export const MyArrayField: Field = { + // ... + admin: { // highlight-line + // ... + }, +} +``` + +The Array Field inherits all of the default options from the base [Field Admin Config](../admin/fields#admin-options), plus the following additional options: | Option | Description | | ------------------------- | -------------------------------------------------------------------------------------------------------------------- | @@ -62,7 +88,7 @@ In addition to the default [field admin config](/docs/fields/overview#admin-conf ## Example -`collections/ExampleCollection.ts` +In this example, we have an Array Field called `slider` that contains a set of fields for a simple image slider. Each row in the array has a `title`, `image`, and `caption`. We also customize the row label to display the title if it exists, or a default label if it doesn't. ```ts import { CollectionConfig } from 'payload' diff --git a/docs/fields/blocks.mdx b/docs/fields/blocks.mdx index f295e453d..5ec2b678e 100644 --- a/docs/fields/blocks.mdx +++ b/docs/fields/blocks.mdx @@ -2,16 +2,17 @@ title: Blocks Field label: Blocks order: 30 -desc: The Blocks field type is a great layout build and can be used to construct any flexible content model. Learn how to use Block fields, see examples and options. +desc: The Blocks Field is a great layout build and can be used to construct any flexible content model. Learn how to use Block Fields, see examples and options. keywords: blocks, fields, config, configuration, documentation, Content Management System, cms, headless, javascript, node, react, nextjs --- - - The Blocks field type is incredibly powerful and can be used as a{' '} - layout builder as well as to define any other flexible content model you can think of. It - stores an array of objects, where each object must match the shape of one of your provided block - configs. - +The Blocks Field is incredibly powerful, storing an array of objects based on the fields that your define, where each item in the array is a "block" with its own unique schema. + +Blocks are a great way to create a flexible content model that can be used to build a wide variety of content types, including: + +- A layout builder tool that grants editors to design highly customizable page or post layouts. Blocks could include configs such as `Quote`, `CallToAction`, `Slider`, `Content`, `Gallery`, or others. +- A form builder tool where available block configs might be `Text`, `Select`, or `Checkbox`. +- Virtual event agenda "timeslots" where a timeslot could either be a `Break`, a `Presentation`, or a `BreakoutSession`. -**Example uses:** +To add a Blocks Field, set the `type` to `blocks` in your [Field Config](./overview): -- A layout builder tool that grants editors to design highly customizable page or post layouts. Blocks could include configs such as `Quote`, `CallToAction`, `Slider`, `Content`, `Gallery`, or others. -- A form builder tool where available block configs might be `Text`, `Select`, or `Checkbox`. -- Virtual event agenda "timeslots" where a timeslot could either be a `Break`, a `Presentation`, or a `BreakoutSession`. +```ts +import type { Field } from 'payload/types' -## Field config +export const MyBlocksField: Field = { + // ... + // highlight-start + type: 'blocks', + blocks: [ + // ... + ], + // highlight-end +} +``` + +## Config Options | Option | Description | | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -44,22 +55,35 @@ keywords: blocks, fields, config, configuration, documentation, Content Manageme | **`localized`** | Enable localization for this field. Requires [localization to be enabled](/docs/configuration/localization) in the Base config. If enabled, a separate, localized set of all data within this field will be kept, so there is no need to specify each nested field as `localized`. | | **`unique`** | Enforce that each entry in the Collection has a unique value for this field. | | **`labels`** | Customize the block row labels appearing in the Admin dashboard. | -| **`admin`** | Admin-specific configuration. See below for [more detail](#admin-config). | +| **`admin`** | Admin-specific configuration. [More details](#admin-options). | | **`custom`** | Extension point for adding custom data (e.g. for plugins) | | **`typescriptSchema`** | Override field type generation with providing a JSON schema | _\* An asterisk denotes that a property is required._ -## Admin Config +## Admin Options -In addition to the default [field admin config](/docs/fields/overview#admin-config), you can adjust the following properties: +The customize the appearance and behavior of the Blocks Field in the [Admin Panel](../admin/overview), you can use the `admin` option: + +```ts +import type { Field } from 'payload/types' + +export const MyBlocksField: Field = { + // ... + admin: { // highlight-line + // ... + }, +} +``` + +The Blocks Field inherits all of the default options from the base [Field Admin Config](../admin/fields#admin-options), plus the following additional options: | Option | Description | | ------------------- | ---------------------------------- | | **`initCollapsed`** | Set the initial collapsed state | | **`isSortable`** | Disable order sorting by setting this value to `false` | -## Block configs +## Block Configs Blocks are defined as separate configs of their own. diff --git a/docs/fields/checkbox.mdx b/docs/fields/checkbox.mdx index 91eeb236d..d2a4024cb 100644 --- a/docs/fields/checkbox.mdx +++ b/docs/fields/checkbox.mdx @@ -6,7 +6,7 @@ desc: Checkbox field types allow the developer to save a boolean value in the da keywords: checkbox, fields, config, configuration, documentation, Content Management System, cms, headless, javascript, node, react, nextjs --- -The Checkbox field type saves a boolean in the database. +The Checkbox Field type saves a boolean in the database. -## Config +To add a Checkbox Field, set the `type` to `checkbox` in your [Field Config](./overview): + +```ts +import type { Field } from 'payload/types' + +export const MyCheckboxField: Field = { + // ... + type: 'checkbox', // highlight-line +} +``` + +## Config Options | Option | Description | | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -30,7 +41,7 @@ keywords: checkbox, fields, config, configuration, documentation, Content Manage | **`defaultValue`** | Provide data to be used for this field's default value, will default to false if field is also `required`. [More](/docs/fields/overview#default-values) | | **`localized`** | Enable localization for this field. Requires [localization to be enabled](/docs/configuration/localization) in the Base config. | | **`required`** | Require this field to have a value. | -| **`admin`** | Admin-specific configuration. See the [default field admin config](/docs/fields/overview#admin-config) for more details. | +| **`admin`** | Admin-specific configuration. [More details](../admin/fields#admin-options). | | **`custom`** | Extension point for adding custom data (e.g. for plugins) | | **`typescriptSchema`** | Override field type generation with providing a JSON schema | @@ -38,7 +49,7 @@ _\* An asterisk denotes that a property is required._ ## Example -`collections/ExampleCollection.ts` +Here is an example of a Checkbox Field in a Collection: ```ts import { CollectionConfig } from 'payload' diff --git a/docs/fields/code.mdx b/docs/fields/code.mdx index 871cc4d38..4f12c7717 100644 --- a/docs/fields/code.mdx +++ b/docs/fields/code.mdx @@ -7,21 +7,27 @@ desc: The Code field type will store any string in the Database. Learn how to us keywords: code, fields, config, configuration, documentation, Content Management System, cms, headless, javascript, node, react, nextjs --- - - The Code field type saves a string in the database, but provides the Admin Panel with a code - editor styled interface. - +The Code Field saves a string in the database, but provides the [Admin Panel](../admin/overview) with a code editor styled interface. -This field uses the `monaco-react` editor syntax highlighting. +To add a Code Field, set the `type` to `code` in your [Field Config](./overview): -## Config +```ts +import type { Field } from 'payload/types' + +export const MyBlocksField: Field = { + // ... + type: 'code', // highlight-line +} +``` + +## Config Options | Option | Description | | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -39,15 +45,28 @@ This field uses the `monaco-react` editor syntax highlighting. | **`defaultValue`** | Provide data to be used for this field's default value. [More](/docs/fields/overview#default-values) | | **`localized`** | Enable localization for this field. Requires [localization to be enabled](/docs/configuration/localization) in the Base config. | | **`required`** | Require this field to have a value. | -| **`admin`** | Admin-specific configuration. See below for [more detail](#admin-config). | +| **`admin`** | Admin-specific configuration. See below for [more detail](#admin-options). | | **`custom`** | Extension point for adding custom data (e.g. for plugins) | | **`typescriptSchema`** | Override field type generation with providing a JSON schema | _\* An asterisk denotes that a property is required._ -## Admin Config +## Admin Options -In addition to the default [field admin config](/docs/fields/overview#admin-config), you can adjust the following properties: +The customize the appearance and behavior of the Code Field in the [Admin Panel](../admin/overview), you can use the `admin` option: + +```ts +import type { Field } from 'payload/types' + +export const MyCodeField: Field = { + // ... + admin: { // highlight-line + // ... + }, +} +``` + +The Code Field inherits all of the default options from the base [Field Admin Config](../admin/fields#admin-options), plus the following additional options: | Option | Description | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | diff --git a/docs/fields/collapsible.mdx b/docs/fields/collapsible.mdx index 2583f1e85..c9586d089 100644 --- a/docs/fields/collapsible.mdx +++ b/docs/fields/collapsible.mdx @@ -6,10 +6,7 @@ desc: With the Collapsible field, you can place fields within a collapsible layo keywords: row, fields, config, configuration, documentation, Content Management System, cms, headless, javascript, node, react, nextjs --- - - The Collapsible field is presentational-only and only affects the Admin Panel. By using it, you - can place fields within a nice layout component that can be collapsed / expanded. - +The Collapsible field is presentational-only and only affects the Admin Panel. By using it, you can place fields within a nice layout component that can be collapsed / expanded. -## Config +To add a Collapsible Field, set the `type` to `collapsible` in your [Field Config](./overview): + +```ts +import type { Field } from 'payload/types' + +export const MyCollapsibleField: Field = { + // ... + // highlight-start + type: 'collapsible', + fields: [ + // ... + ], + // highlight-end +} +``` + +## Config Options | Option | Description | | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **`label`** \* | A label to render within the header of the collapsible component. This can be a string, function or react component. Function/components receive `({ data, path })` as args. | | **`fields`** \* | Array of field types to nest within this Collapsible. | -| **`admin`** | Admin-specific configuration. See below for [more detail](#admin-config). | +| **`admin`** | Admin-specific configuration. [More details](#admin-options). | | **`custom`** | Extension point for adding custom data (e.g. for plugins) | _\* An asterisk denotes that a property is required._ -## Admin Config +## Admin Options -In addition to the default [field admin config](/docs/fields/overview#admin-config), you can adjust the following properties: +The customize the appearance and behavior of the Collapsible Field in the [Admin Panel](../admin/overview), you can use the `admin` option: + +```ts +import type { Field } from 'payload/types' + +export const MyCollapsibleField: Field = { + // ... + admin: { // highlight-line + // ... + }, +} +``` + +The Collapsible Field inherits all of the default options from the base [Field Admin Config](../admin/fields#admin-options), plus the following additional options: | Option | Description | | ------------------- | ------------------------------- | diff --git a/docs/fields/date.mdx b/docs/fields/date.mdx index ea3f8b1d6..62e1b45cb 100644 --- a/docs/fields/date.mdx +++ b/docs/fields/date.mdx @@ -6,21 +6,27 @@ desc: The Date field type stores a Date in the database. Learn how to use and cu keywords: date, fields, config, configuration, documentation, Content Management System, cms, headless, javascript, node, react, nextjs --- - - The Date field type saves a Date in the database and provides the Admin Panel with a customizable - time picker interface. - +The Date Field saves a Date in the database and provides the [Admin Panel](../admin/overview) with a customizable time picker interface. -This field uses [`react-datepicker`](https://www.npmjs.com/package/react-datepicker) for the Admin Panel component. +To add a Date Field, set the `type` to `date` in your [Field Config](./overview): -## Config +```ts +import type { Field } from 'payload/types' + +export const MyDateField: Field = { + // ... + type: 'date', // highlight-line +} +``` + +## Config Options | Option | Description | | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -35,15 +41,28 @@ This field uses [`react-datepicker`](https://www.npmjs.com/package/react-datepic | **`defaultValue`** | Provide data to be used for this field's default value. [More](/docs/fields/overview#default-values) | | **`localized`** | Enable localization for this field. Requires [localization to be enabled](/docs/configuration/localization) in the Base config. | | **`required`** | Require this field to have a value. | -| **`admin`** | Admin-specific configuration. See below for [more detail](#admin-config). | +| **`admin`** | Admin-specific configuration. [More details](#admin-options). | | **`custom`** | Extension point for adding custom data (e.g. for plugins) | | **`typescriptSchema`** | Override field type generation with providing a JSON schema | _\* An asterisk denotes that a property is required._ -## Admin Config +## Admin Options -In addition to the default [field admin config](/docs/fields/overview#admin-config), you can customize the following fields that will adjust how the component displays in the Admin Panel via the `date` property. +The customize the appearance and behavior of the Date Field in the [Admin Panel](../admin/overview), you can use the `admin` option: + +```ts +import type { Field } from 'payload/types' + +export const MyDateField: Field = { + // ... + admin: { // highlight-line + // ... + }, +} +``` + +The Date Field inherits all of the default options from the base [Field Admin Config](../admin/fields#admin-options), plus the following additional options: | Property | Description | | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------- | diff --git a/docs/fields/email.mdx b/docs/fields/email.mdx index 7f31694b2..e2beef874 100644 --- a/docs/fields/email.mdx +++ b/docs/fields/email.mdx @@ -6,7 +6,7 @@ desc: The Email field enforces that the value provided is a valid email address. keywords: email, fields, config, configuration, documentation, Content Management System, cms, headless, javascript, node, react, nextjs --- -The Email field enforces that the value provided is a valid email address. +The Email Field enforces that the value provided is a valid email address. -## Config +To create an Email Field, set the `type` to `email` in your [Field Config](./overview): + +```ts +import type { Field } from 'payload/types' + +export const MyEmailField: Field = { + // ... + type: 'email', // highlight-line +} +``` + +## Config Options | Option | Description | | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -31,23 +42,33 @@ keywords: email, fields, config, configuration, documentation, Content Managemen | **`defaultValue`** | Provide data to be used for this field's default value. [More](/docs/fields/overview#default-values) | | **`localized`** | Enable localization for this field. Requires [localization to be enabled](/docs/configuration/localization) in the Base config. | | **`required`** | Require this field to have a value. | -| **`admin`** | Admin-specific configuration. See below for [more detail](#admin-config). | +| **`admin`** | Admin-specific configuration. [More details](#admin-options). | | **`custom`** | Extension point for adding custom data (e.g. for plugins) | | **`typescriptSchema`** | Override field type generation with providing a JSON schema | _\* An asterisk denotes that a property is required._ -## Admin config +## Admin Options -In addition to the default [field admin config](/docs/fields/overview#admin-config), this field type allows for the following `admin` properties: +The customize the appearance and behavior of the Email Field in the [Admin Panel](../admin/overview), you can use the `admin` option: -**`placeholder`** +```ts +import type { Field } from 'payload/types' -Set this property to define a placeholder string for the field. +export const MyEmailField: Field = { + // ... + admin: { // highlight-line + // ... + }, +} +``` -**`autoComplete`** +The Email Field inherits all of the default options from the base [Field Admin Config](../admin/fields#admin-options), plus the following additional options: -Set this property to a string that will be used for browser autocomplete. +| Property | Description | +| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------- | +| **`placeholder`** | Set this property to define a placeholder string for the field. | +| **`autoComplete`** | Set this property to a string that will be used for browser autocomplete. | ## Example diff --git a/docs/fields/group.mdx b/docs/fields/group.mdx index 026ea8d60..8eba5b530 100644 --- a/docs/fields/group.mdx +++ b/docs/fields/group.mdx @@ -6,10 +6,7 @@ desc: The Group field allows other fields to be nested under a common property. keywords: group, fields, config, configuration, documentation, Content Management System, cms, headless, javascript, node, react, nextjs --- - - The Group field allows fields to be nested under a common property name. It also groups fields - together visually in the Admin Panel. - +The Group Field allows [Fields](./overview) to be nested under a common property name. It also groups fields together visually in the [Admin Panel](../admin/overview). -## Config +To add a Group Field, set the `type` to `group` in your [Field Config](./overview): + +```ts +import type { Field } from 'payload/types' + +export const MyGroupField: Field = { + // ... + // highlight-start + type: 'group', + fields: [ + // ... + ], + // highlight-end +} +``` + +## Config Options | Option | Description | | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -32,20 +45,33 @@ keywords: group, fields, config, configuration, documentation, Content Managemen | **`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 an object of data to be used for this field's default value. [More](/docs/fields/overview#default-values) | | **`localized`** | Enable localization for this field. Requires [localization to be enabled](/docs/configuration/localization) in the Base config. If enabled, a separate, localized set of all data within this Group will be kept, so there is no need to specify each nested field as `localized`. | -| **`admin`** | Admin-specific configuration. See below for [more detail](#admin-config). | +| **`admin`** | Admin-specific configuration. [More details](#admin-options). | | **`custom`** | Extension point for adding custom data (e.g. for plugins) | | **`interfaceName`** | Create a top level, reusable [Typescript interface](/docs/typescript/generating-types#custom-field-interfaces) & [GraphQL type](/docs/graphql/graphql-schema#custom-field-schemas). | | **`typescriptSchema`** | Override field type generation with providing a JSON schema | _\* An asterisk denotes that a property is required._ -## Admin config +## Admin Options -In addition to the default [field admin config](/docs/fields/overview#admin-config), the Group allows for the following admin property: +The customize the appearance and behavior of the Group Field in the [Admin Panel](../admin/overview), you can use the `admin` option: -**`hideGutter`** +```ts +import type { Field } from 'payload/types' -Set this property to `true` to hide this field's gutter within the Admin Panel. The field gutter is rendered as a vertical line and padding, but often if this field is nested within a Group, Block, or Array, you may want to hide the gutter. +export const MyGroupField: Field = { + // ... + admin: { // highlight-line + // ... + }, +} +``` + +The Group Field inherits all of the default options from the base [Field Admin Config](../admin/fields#admin-options), plus the following additional options: + +| Option | Description | +| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **`hideGutter`** | Set this property to `true` to hide this field's gutter within the Admin Panel. The field gutter is rendered as a vertical line and padding, but often if this field is nested within a Group, Block, or Array, you may want to hide the gutter. | ## Example diff --git a/docs/fields/json.mdx b/docs/fields/json.mdx index 545a05c80..8535ffbcc 100644 --- a/docs/fields/json.mdx +++ b/docs/fields/json.mdx @@ -7,21 +7,27 @@ desc: The JSON field type will store any string in the Database. Learn how to us keywords: json, jsonSchema, schema, validation, fields, config, configuration, documentation, Content Management System, cms, headless, javascript, node, react, nextjs --- - - The JSON field type saves actual JSON in the database, which differs from the Code field that - saves the value as a string in the database. - +The JSON Field saves actual JSON in the database, which differs from the Code field that saves the value as a string in the database. -This field uses the `monaco-react` editor syntax highlighting. +To add a JSON Field, set the `type` to `json` in your [Field Config](./overview): -## Config +```ts +import type { Field } from 'payload/types' + +export const MyJSONField: Field = { + // ... + type: 'json', // highlight-line +} +``` + +## Config Options | Option | Description | | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -38,15 +44,28 @@ This field uses the `monaco-react` editor syntax highlighting. | **`defaultValue`** | Provide data to be used for this field's default value. [More](/docs/fields/overview#default-values) | | **`localized`** | Enable localization for this field. Requires [localization to be enabled](/docs/configuration/localization) in the Base config. | | **`required`** | Require this field to have a value. | -| **`admin`** | Admin-specific configuration. See below for [more detail](#admin-config). | +| **`admin`** | Admin-specific configuration. [More details](#admin-options). | | **`custom`** | Extension point for adding custom data (e.g. for plugins) | | **`typescriptSchema`** | Override field type generation with providing a JSON schema | _\* An asterisk denotes that a property is required._ -## Admin Config +## Admin Options -In addition to the default [field admin config](/docs/fields/overview#admin-config), you can adjust the following properties: +The customize the appearance and behavior of the JSON Field in the [Admin Panel](../admin/overview), you can use the `admin` option: + +```ts +import type { Field } from 'payload/types' + +export const MyJSONField: Field = { + // ... + admin: { // highlight-line + // ... + }, +} +``` + +The JSON Field inherits all of the default options from the base [Field Admin Config](../admin/fields#admin-options), plus the following additional options: | Option | Description | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | diff --git a/docs/fields/number.mdx b/docs/fields/number.mdx index cbb67d7e9..071be025a 100644 --- a/docs/fields/number.mdx +++ b/docs/fields/number.mdx @@ -6,10 +6,7 @@ desc: Number fields store and validate numeric data. Learn how to use and format keywords: number, fields, config, configuration, documentation, Content Management System, cms, headless, javascript, node, react, nextjs --- - - The Number field stores and validates numeric entry and supports additional numerical validation - and formatting features. - +The Number Field stores and validates numeric entry and supports additional numerical validation and formatting features. -## Config +To add a Number Field, set the `type` to `number` in your [Field Config](./overview): + +```ts +import type { Field } from 'payload/types' + +export const MyNumberField: Field = { + // ... + type: 'number', // highlight-line +} +``` + +## Config Options | Option | Description | | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -39,27 +47,34 @@ keywords: number, fields, config, configuration, documentation, Content Manageme | **`defaultValue`** | Provide data to be used for this field's default value. [More](/docs/fields/overview#default-values) | | **`localized`** | Enable localization for this field. Requires [localization to be enabled](/docs/configuration/localization) in the Base config. | | **`required`** | Require this field to have a value. | -| **`admin`** | Admin-specific configuration. See below for [more detail](#admin-config). | +| **`admin`** | Admin-specific configuration. [More details](#admin-options). | | **`custom`** | Extension point for adding custom data (e.g. for plugins) | | **`typescriptSchema`** | Override field type generation with providing a JSON schema | _\* An asterisk denotes that a property is required._ -## Admin config +## Admin Options -In addition to the default [field admin config](/docs/fields/overview#admin-config), this field type allows for the following `admin` properties: +The customize the appearance and behavior of the Number Field in the [Admin Panel](../admin/overview), you can use the `admin` option: -**`step`** +```ts +import type { Field } from 'payload/types' -Set a value for the number field to increment / decrement using browser controls. +export const MyNumberField: Field = { + // ... + admin: { // highlight-line + // ... + }, +} +``` -**`placeholder`** +The Number Field inherits all of the default options from the base [Field Admin Config](../admin/fields#admin-options), plus the following additional options: -Set this property to define a placeholder string for the field. - -**`autoComplete`** - -Set this property to a string that will be used for browser autocomplete. +| Property | Description | +| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------- | +| **`step`** | Set a value for the number field to increment / decrement using browser controls. | +| **`placeholder`** | Set this property to define a placeholder string for the field. | +| **`autoComplete`** | Set this property to a string that will be used for browser autocomplete. | ## Example diff --git a/docs/fields/point.mdx b/docs/fields/point.mdx index 324977f5c..15ec21647 100644 --- a/docs/fields/point.mdx +++ b/docs/fields/point.mdx @@ -3,18 +3,10 @@ title: Point Field label: Point order: 110 desc: The Point field type stores coordinates in the database. Learn how to use Point field for geolocation and geometry. - keywords: point, geolocation, geospatial, geojson, 2dsphere, config, configuration, documentation, Content Management System, cms, headless, javascript, node, react, nextjs --- - - The Point field type saves a pair of coordinates in the database and assigns an index for location - related queries. - - - - Note: The Point field type is currently only supported in MongoDB. - +The Point Field saves a pair of coordinates in the database and assigns an index for location related queries. The data structure in the database matches the GeoJSON structure to represent point. The Payload APIs simplifies the object data to only the [longitude, latitude] location. -The data structure in the database matches the GeoJSON structure to represent point. The Payload APIs simplifies the object data to only the [longitude, latitude] location. +To add a Point Field, set the `type` to `point` in your [Field Config](./overview): + +```ts +import type { Field } from 'payload/types' + +export const MyPointField: Field = { + // ... + type: 'point', // highlight-line +} +``` + + + Important: + The Point Field is currently only supported in MongoDB. + ## Config @@ -41,16 +47,12 @@ The data structure in the database matches the GeoJSON structure to represent po | **`defaultValue`** | Provide data to be used for this field's default value. [More](/docs/fields/overview#default-values) | | **`localized`** | Enable localization for this field. Requires [localization to be enabled](/docs/configuration/localization) in the Base config. | | **`required`** | Require this field to have a value. | -| **`admin`** | Admin-specific configuration. See below for [more detail](#admin-config). | +| **`admin`** | Admin-specific configuration. [More details](../admin/fields#admin-options). | | **`custom`** | Extension point for adding custom data (e.g. for plugins) | | **`typescriptSchema`** | Override field type generation with providing a JSON schema | _\* An asterisk denotes that a property is required._ - - Note: The Point field type is currently only supported in MongoDB. - - ## Example `collections/ExampleCollection.ts` diff --git a/docs/fields/radio.mdx b/docs/fields/radio.mdx index 9f0b026f9..f7f3c518d 100644 --- a/docs/fields/radio.mdx +++ b/docs/fields/radio.mdx @@ -6,10 +6,7 @@ desc: The Radio field type allows for the selection of one value from a predefin keywords: radio, fields, config, configuration, documentation, Content Management System, cms, headless, javascript, node, react, nextjs --- - - The Radio Group field type allows for the selection of one value from a predefined set of possible - values and presents a radio group-style set of inputs to the Admin Panel. - +The Radio Field allows for the selection of one value from a predefined set of possible values and presents a radio group-style set of inputs to the [Admin Panel](../admin/overview). -## Config +To add a Radio Field, set the `type` to `radio` in your [Field Config](./overview): + +```ts +import type { Field } from 'payload/types' + +export const MyRadioField: Field = { + // ... + // highlight-start + type: 'radio', + options: [ + // ... + ] + // highlight-end +} +``` + +## Config Options | Option | Description | | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -34,7 +47,7 @@ keywords: radio, fields, config, configuration, documentation, Content Managemen | **`defaultValue`** | Provide data to be used for this field's default value. The default value must exist within provided values in `options`. [More](/docs/fields/overview#default-values) | | **`localized`** | Enable localization for this field. Requires [localization to be enabled](/docs/configuration/localization) in the Base config. | | **`required`** | Require this field to have a value. | -| **`admin`** | Admin-specific configuration. See below for [more detail](#admin-config). | +| **`admin`** | Admin-specific configuration. [More details](#admin-options). | | **`custom`** | Extension point for adding custom data (e.g. for plugins) | | **`enumName`** | Custom enum name for this field when using SQL Database Adapter ([Postgres](/docs/database/postgres)). Auto-generated from name if not defined. | | **`typescriptSchema`** | Override field type generation with providing a JSON schema | @@ -50,13 +63,26 @@ _\* An asterisk denotes that a property is required._ being used as a GraphQL enum. -## Admin config +## Admin Options -In addition to the default [field admin config](/docs/fields/overview#admin-config), the Radio Group field type allows for the specification of the following `admin` properties: +The customize the appearance and behavior of the Radio Field in the [Admin Panel](../admin/overview), you can use the `admin` option: -**`layout`** +```ts +import type { Field } from 'payload/types' -The `layout` property allows for the radio group to be styled as a horizonally or vertically distributed list. The default value is `horizontal`. +export const MyRadioField: Field = { + // ... + admin: { // highlight-line + // ... + }, +} +``` + +The Radio Field inherits all of the default options from the base [Field Admin Config](../admin/fields#admin-options), plus the following additional options: + +| Property | Description | +| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------- | +| **`layout`** | Allows for the radio group to be styled as a horizonally or vertically distributed list. The default value is `horizontal`. | ## Example diff --git a/docs/fields/relationship.mdx b/docs/fields/relationship.mdx index 209301a86..23c041387 100644 --- a/docs/fields/relationship.mdx +++ b/docs/fields/relationship.mdx @@ -6,10 +6,7 @@ desc: The Relationship field provides the ability to relate documents together. keywords: relationship, fields, config, configuration, documentation, Content Management System, cms, headless, javascript, node, react, nextjs --- - - The Relationship field is one of the most powerful fields Payload features. It provides for the - ability to easily relate documents together. - +The Relationship field is one of the most powerful fields Payload features. It provides for the ability to easily relate documents together. -**Example uses:** +The Relationship field is used in a variety of ways, including: - To add `Product` documents to an `Order` document - To allow for an `Order` to feature a `placedBy` relationship to either an `Organization` or `User` collection - To assign `Category` documents to `Post` documents -## Config +To add a Relationship Field, set the `type` to `relationship` in your [Field Config](./overview): + +```ts +import type { Field } from 'payload/types' + +export const MyRelationshipField: Field = { + // ... + // highlight-start + type: 'relationship', + relationTo: 'products', + // highlight-end +} +``` + +## Config Options | Option | Description | | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -46,7 +57,7 @@ keywords: relationship, fields, config, configuration, documentation, Content Ma | **`defaultValue`** | Provide data to be used for this field's default value. [More](/docs/fields/overview#default-values) | | **`localized`** | Enable localization for this field. Requires [localization to be enabled](/docs/configuration/localization) in the Base config. | | **`required`** | Require this field to have a value. | -| **`admin`** | Admin-specific configuration. See the [default field admin config](/docs/fields/overview#admin-config) for more details. | +| **`admin`** | Admin-specific configuration. [More details](#admin-options). | | **`custom`** | Extension point for adding custom data (e.g. for plugins) | | **`typescriptSchema`** | Override field type generation with providing a JSON schema | @@ -54,30 +65,33 @@ _\* An asterisk denotes that a property is required._ Tip: -
- The [Depth](../queries/depth) parameter can be used to automatically populate - related documents that are returned by the API. + The [Depth](../queries/depth) parameter can be used to automatically populate related documents that are returned by the API. -## Admin config +## Admin Options -In addition to the default [field admin config](/docs/fields/overview#admin-config), the Relationship field type also -allows for the following admin-specific properties: +The customize the appearance and behavior of the Relationship Field in the [Admin Panel](../admin/overview), you can use the `admin` option: -**`isSortable`** +```ts +import type { Field } from 'payload/types' -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`). +export const MyRelationshipField: Field = { + // ... + admin: { // highlight-line + // ... + }, +} +``` -**`allowCreate`** +The Relationship Field inherits all of the default options from the base [Field Admin Config](../admin/fields#admin-options), plus the following additional options: -Set to `false` if you'd like to disable the ability to create new documents from within the relationship field (hides -the "Add new" button in the admin UI). +| Property | Description | +| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- | +| **`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`). | +| **`allowCreate`** | Set to `false` if you'd like to disable the ability to create new documents from within the relationship field. | +| **`sortOptions`** | Define a default sorting order for the options within a Relationship field's dropdown. [More](#sortOptions) | -**`sortOptions`** - -The `sortOptions` property allows you to define a default sorting order for the options within a Relationship field's -dropdown. This can be particularly useful for ensuring that the most relevant options are presented first to the user. +### Sort Options You can specify `sortOptions` in two ways: diff --git a/docs/fields/rich-text.mdx b/docs/fields/rich-text.mdx index 06d4dd43d..87f77ec25 100644 --- a/docs/fields/rich-text.mdx +++ b/docs/fields/rich-text.mdx @@ -6,10 +6,7 @@ desc: The Rich Text field allows dynamic content to be written through the Admin keywords: rich text, fields, config, configuration, documentation, Content Management System, cms, headless, javascript, node, react, nextjs --- - - The Rich Text field is a powerful way to allow editors to write dynamic content. The content is - saved as JSON in the database and can be converted into any format, including HTML, that you need. - +The Rich Text Field is a powerful way to allow editors to write dynamic content. The content is saved as JSON in the database and can be converted into any format, including HTML, that you need. -## Config +## Config Options | Option | Description | | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -53,29 +50,36 @@ Right now, Payload is officially supporting two rich text editors: | **`defaultValue`** | Provide data to be used for this field's default value. [More](/docs/fields/overview#default-values) | | **`localized`** | Enable localization for this field. Requires [localization to be enabled](/docs/configuration/localization) in the Base config. | | **`required`** | Require this field to have a value. | -| **`admin`** | Admin-specific configuration. See below for [more detail](#admin-config). | +| **`admin`** | Admin-specific configuration. [More details](#admin-options). | | **`editor`** | Override the rich text editor specified in your base configuration for this field. | | **`custom`** | Extension point for adding custom data (e.g. for plugins) | | **`typescriptSchema`** | Override field type generation with providing a JSON schema | _\* An asterisk denotes that a property is required._ -## Admin config +## Admin Options -In addition to the default [field admin config](/docs/fields/overview#admin-config), the Rich Text editor allows for the following admin properties: +The customize the appearance and behavior of the Rich Text Field in the [Admin Panel](../admin/overview), you can use the `admin` option: -**`placeholder`** +```ts +import type { Field } from 'payload/types' -Set this property to define a placeholder string in the text input. +export const MyRichTextField: Field = { + // ... + admin: { // highlight-line + // ... + }, +} +``` -**`hideGutter`** +The Rich Text Field inherits all of the default options from the base [Field Admin Config](../admin/fields#admin-options), plus the following additional options: -Set this property to `true` to hide this field's gutter within the Admin Panel. The field gutter is rendered as a vertical line and padding, but often if this field is nested within a Group, Block, or Array, you may want to hide the gutter. +| Property | Description | +| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------- | +| **`placeholder`** | Set this property to define a placeholder string for the field. | +| **`hideGutter`** | Set this property to `true` to hide this field's gutter within the Admin Panel. | +| **`rtl`** | Override the default text direction of the Admin Panel for this field. Set to `true` to force right-to-left text direction. | -**`rtl`** - -Override the default text direction of the Admin Panel for this field. Set to `true` to force right-to-left text direction. - -## Editor-specific options +## Editor-specific Options For a ton more editor-specific options, including how to build custom rich text elements directly into your editor, take a look at either the [Slate docs](/docs/rich-text/slate) or the [Lexical docs](/docs/rich-text/lexical) depending on which editor you're using. diff --git a/docs/fields/row.mdx b/docs/fields/row.mdx index 6bfb79bed..125dd3ba3 100644 --- a/docs/fields/row.mdx +++ b/docs/fields/row.mdx @@ -6,10 +6,7 @@ desc: With the Row field you can arrange fields next to each other in the Admin keywords: row, fields, config, configuration, documentation, Content Management System, cms, headless, javascript, node, react, nextjs --- - - The Row field is presentational-only and only affects the Admin Panel. By using it, you can - arrange fields next to each other horizontally. - +The Row Field is presentational-only and only affects the [Admin Panel](../admin/overview). By using it, you can arrange [Fields](./overview) next to each other horizontally. -## Config +To add a Row Field, set the `type` to `row` in your [Field Config](./overview): + +```ts +import type { Field } from 'payload/types' + +export const MyRowField: Field = { + // ... + // highlight-start + type: 'row', + fields: [ + // ... + ] + // highlight-end +} +``` + +## Config Options | Option | Description | | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **`fields`** \* | Array of field types to nest within this Row. | -| **`admin`** | Admin-specific configuration excluding `description`, `readOnly`, and `hidden`. See the [default field admin config](/docs/fields/overview#admin-config) for more details. | +| **`admin`** | Admin-specific configuration excluding `description`, `readOnly`, and `hidden`. [More details](../admin/fields#admin-options). | | **`custom`** | Extension point for adding custom data (e.g. for plugins) | _\* An asterisk denotes that a property is required._ diff --git a/docs/fields/select.mdx b/docs/fields/select.mdx index fdbea6f4f..4e5936a4a 100644 --- a/docs/fields/select.mdx +++ b/docs/fields/select.mdx @@ -6,10 +6,7 @@ desc: The Select field provides a dropdown-style interface for choosing options keywords: select, multi-select, fields, config, configuration, documentation, Content Management System, cms, headless, javascript, node, react, nextjs --- - - The Select field provides a dropdown-style interface for choosing options from a predefined list - as an enumeration. - +The Select Field provides a dropdown-style interface for choosing options from a predefined list as an enumeration. -## Config +To add a Select Field, set the `type` to `select` in your [Field Config](./overview): + +```ts +import type { Field } from 'payload/types' + +export const MySelectField: Field = { + // ... + // highlight-start + type: 'select', + options: [ + // ... + ] + // highlight-end +} +``` + +## Config Options | Option | Description | | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -36,7 +49,7 @@ keywords: select, multi-select, fields, config, configuration, documentation, Co | **`defaultValue`** | Provide data to be used for this field's default value. [More](/docs/fields/overview#default-values) | | **`localized`** | Enable localization for this field. Requires [localization to be enabled](/docs/configuration/localization) in the Base config. | | **`required`** | Require this field to have a value. | -| **`admin`** | Admin-specific configuration. See the [default field admin config](/docs/fields/overview#admin-config) for more details. | +| **`admin`** | Admin-specific configuration. See the [default field admin config](/docs/fields/overview#admin-options) 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](/docs/database/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](/docs/database/postgres)). Auto-generated from name if not defined. | @@ -46,24 +59,33 @@ _\* An asterisk denotes that a property is required._ Important: -
Option values should be strings that do not contain hyphens or special characters due to GraphQL enumeration naming constraints. Underscores are allowed. If you determine you need your option values to be non-strings or contain special characters, they will be formatted accordingly before being used as a GraphQL enum. -## Admin config +## Admin Options -In addition to the default [field admin config](/docs/fields/overview#admin-config), the Select field type also allows for the following admin-specific properties: +The customize the appearance and behavior of the Select Field in the [Admin Panel](../admin/overview), you can use the `admin` option: -**`isClearable`** +```ts +import type { Field } from 'payload/types' -Set to `true` if you'd like this field to be clearable within the Admin UI. +export const MySelectField: Field = { + // ... + admin: { // highlight-line + // ... + }, +} +``` -**`isSortable`** +The Select Field inherits all of the default options from the base [Field Admin Config](../admin/fields#admin-options), plus the following additional options: -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`) +| 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 diff --git a/docs/fields/tabs.mdx b/docs/fields/tabs.mdx index 3a607d38a..5f365627a 100644 --- a/docs/fields/tabs.mdx +++ b/docs/fields/tabs.mdx @@ -6,11 +6,7 @@ desc: The Tabs field is a great way to organize complex editing experiences into keywords: tabs, fields, config, configuration, documentation, Content Management System, cms, headless, javascript, node, react, nextjs --- - - The Tabs field is presentational-only and only affects the Admin Panel (unless a tab is named). By - using it, you can place fields within a nice layout component that separates certain sub-fields by - a tabbed interface. - +The Tabs Field is presentational-only and only affects the [Admin Panel](../admin/overview) (unless a tab is named). By using it, you can place fields within a nice layout component that separates certain sub-fields by a tabbed interface. -## Config +To add a Tabs Field, set the `type` to `tabs` in your [Field Config](./overview): + +```ts +import type { Field } from 'payload/types' + +export const MyTabsField: Field = { + // ... + // highlight-start + type: 'tabs', + tabs: [ + // ... + ] + // highlight-end +} +``` + +## Config Options | Option | Description | | ------------- | ------------------------------------------------------------------------------------------------------------------------ | | **`tabs`** \* | Array of tabs to render within this Tabs field. | -| **`admin`** | Admin-specific configuration. See the [default field admin config](/docs/fields/overview#admin-config) for more details. | +| **`admin`** | Admin-specific configuration. [More details](../admin/fields#admin-options). | | **`custom`** | Extension point for adding custom data (e.g. for plugins) | ### Tab-specific Config diff --git a/docs/fields/text.mdx b/docs/fields/text.mdx index b70e8c754..754b9aa2a 100644 --- a/docs/fields/text.mdx +++ b/docs/fields/text.mdx @@ -6,10 +6,7 @@ desc: Text field types simply save a string to the database and provide the Admi keywords: text, fields, config, configuration, documentation, Content Management System, cms, headless, javascript, node, react, nextjs --- - - The Text field type is one of the most commonly used fields. It saves a string to the database and - provides the Admin Panel with a simple text input. - +The Text Field is one of the most commonly used fields. It saves a string to the database and provides the [Admin Panel](../admin/overview) with a simple text input. -## Config +To add a Text Field, set the `type` to `text` in your [Field Config](./overview): + +```ts +import type { Field } from 'payload/types' + +export const MyTextField: Field = { + // ... + type: 'text', // highlight-line +} +``` + +## Config Options | Option | Description | | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -36,7 +44,7 @@ keywords: text, fields, config, configuration, documentation, Content Management | **`defaultValue`** | Provide data to be used for this field's default value. [More](/docs/fields/overview#default-values) | | **`localized`** | Enable localization for this field. Requires [localization to be enabled](/docs/configuration/localization) in the Base config. | | **`required`** | Require this field to have a value. | -| **`admin`** | Admin-specific configuration. See below for [more detail](#admin-config). | +| **`admin`** | Admin-specific configuration. [More details](#admin-options). | | **`custom`** | Extension point for adding custom data (e.g. for plugins) | | **`hasMany`** | Makes this field an ordered array of text instead of just a single text. | | **`minRows`** | Minimum number of texts in the array, if `hasMany` is set to true. | @@ -45,21 +53,28 @@ keywords: text, fields, config, configuration, documentation, Content Management _\* An asterisk denotes that a property is required._ -## Admin config +## Admin Options -In addition to the default [field admin config](/docs/fields/overview#admin-config), the Text field type allows for the following `admin` properties: +The customize the appearance and behavior of the Text Field in the [Admin Panel](../admin/overview), you can use the `admin` option: -**`placeholder`** +```ts +import type { Field } from 'payload/types' -Set this property to define a placeholder string in the text input. +export const MyTextField: Field = { + // ... + admin: { // highlight-line + // ... + }, +} +``` -**`autoComplete`** +The Text Field inherits all of the default options from the base [Field Admin Config](../admin/fields#admin-options), plus the following additional options: -Set this property to a string that will be used for browser autocomplete. - -**`rtl`** - -Override the default text direction of the Admin Panel for this field. Set to `true` to force right-to-left text direction. +| Option | Description | +| -------------- | ---------------------------------------------------------------------------------------------------------------- | +| **`placeholder`** | Set this property to define a placeholder string in the text input. | +| **`autoComplete`** | Set this property to a string that will be used for browser autocomplete. | +| **`rtl`** | Override the default text direction of the Admin Panel for this field. Set to `true` to force right-to-left text direction. | ## Example diff --git a/docs/fields/textarea.mdx b/docs/fields/textarea.mdx index bf4e49966..3311da419 100644 --- a/docs/fields/textarea.mdx +++ b/docs/fields/textarea.mdx @@ -6,10 +6,7 @@ desc: Textarea field types save a string to the database, similar to the Text fi keywords: textarea, fields, config, configuration, documentation, Content Management System, cms, headless, javascript, node, react, nextjs --- - - The Textarea field is almost identical to the Text field but it features a slightly larger input - that is better suited to edit longer text. - +The Textarea Field is nearly identical to the [Text Field](./text) but it features a slightly larger input that is better suited to edit longer text. -## Config +To add a Textarea Field, set the `type` to `textarea` in your [Field Config](./overview): + +```ts +import type { Field } from 'payload/types' + +export const MyTextareaField: Field = { + // ... + type: 'textarea', // highlight-line +} +``` + +## Config Options | Option | Description | | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -36,27 +44,34 @@ keywords: textarea, fields, config, configuration, documentation, Content Manage | **`defaultValue`** | Provide data to be used for this field's default value. [More](/docs/fields/overview#default-values) | | **`localized`** | Enable localization for this field. Requires [localization to be enabled](/docs/configuration/localization) in the Base config. | | **`required`** | Require this field to have a value. | -| **`admin`** | Admin-specific configuration. See below for [more detail](#admin-config). | +| **`admin`** | Admin-specific configuration. [More details](#admin-options). | | **`custom`** | Extension point for adding custom data (e.g. for plugins) | | **`typescriptSchema`** | Override field type generation with providing a JSON schema | _\* An asterisk denotes that a property is required._ -## Admin config +## Admin Options -In addition to the default [field admin config](/docs/fields/overview#admin-config), the Textarea field type allows for the following `admin` properties: +The customize the appearance and behavior of the Textarea Field in the [Admin Panel](../admin/overview), you can use the `admin` option: -**`placeholder`** +```ts +import type { Field } from 'payload/types' -Set this property to define a placeholder string in the textarea. +export const MyTextareaField: Field = { + // ... + admin: { // highlight-line + // ... + }, +} +``` -**`autoComplete`** +The Textarea Field inherits all of the default options from the base [Field Admin Config](../admin/fields#admin-options), plus the following additional options: -Set this property to a string that will be used for browser autocomplete. - -**`rtl`** - -Override the default text direction of the Admin Panel for this field. Set to `true` to force right-to-left text direction. +| Option | Description | +| -------------- | ---------------------------------------------------------------------------------------------------------------- | +| **`placeholder`** | Set this property to define a placeholder string in the textarea. | +| **`autoComplete`** | Set this property to a string that will be used for browser autocomplete. | +| **`rtl`** | Override the default text direction of the Admin Panel for this field. Set to `true` to force right-to-left text direction. | ## Example diff --git a/docs/fields/ui.mdx b/docs/fields/ui.mdx index ce2046075..32e42afbd 100644 --- a/docs/fields/ui.mdx +++ b/docs/fields/ui.mdx @@ -6,31 +6,34 @@ desc: UI fields are purely presentational and allow developers to customize the keywords: custom field, react component, fields, config, configuration, documentation, Content Management System, cms, headless, javascript, node, react, nextjs --- - - The UI (user interface) field gives you a ton of power to add your own React components directly - into the Admin Panel, nested directly within your other fields. It has absolutely no effect on the - data of your documents. It is presentational-only. - +The UI (user interface) Field gives you a ton of power to add your own React components directly into the [Admin Panel](../admin/overview), nested directly within your other fields. It has absolutely no effect on the data of your documents. It is presentational-only. Think of it as a way for you to "plug in" your own React components directly within your other fields, so you can provide your editors with new controls exactly where you want them to go. -This field is helpful if you need to build in custom functionality via React components within the Admin Panel. Think of it as a way for you to "plug in" your own React components directly within your other fields, so you can provide your editors with new controls exactly where you want them to go. - -With this field, you can also inject custom `Cell` components that appear as additional columns within collections' List views. - -**Example uses:** +With the UI Field, you can: - Add a custom message or block of text within the body of an Edit View to describe the purpose of surrounding fields - Add a "Refund" button to an Order's Edit View sidebar, which might make a fetch call to a custom `refund` endpoint - Add a "view page" button into a Pages List View to give editors a shortcut to view a page on the frontend of the site - Build a "clear cache" button or similar mechanism to manually clear caches of specific documents -## Config +To add a UI Field, set the `type` to `ui` in your [Field Config](./overview): + +```ts +import type { Field } from 'payload/types' + +export const MyUIField: Field = { + // ... + type: 'ui', // highlight-line +} +``` + +## Config Options | Option | Description | | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | | **`name`** \* | A unique identifier for this field. | | **`label`** | Human-readable label for this UI field. | -| **`admin.components.Field`** \* | React component to be rendered for this field within the Edit View. [More](/docs/admin/components/#field-component) | -| **`admin.components.Cell`** | React component to be rendered as a Cell within collection List views. [More](/docs/admin/components/#field-component) | +| **`admin.components.Field`** \* | React component to be rendered for this field within the Edit View. [More](../admin/components/#field-component) | +| **`admin.components.Cell`** | React component to be rendered as a Cell within collection List views. [More](../admin/components/#field-component) | | **`admin.disableListColumn`** | Set `disableListColumn` to `true` to prevent the UI field from appearing in the list view column selector. | | **`custom`** | Extension point for adding custom data (e.g. for plugins) | diff --git a/docs/fields/upload.mdx b/docs/fields/upload.mdx index f78028e16..6666c4707 100644 --- a/docs/fields/upload.mdx +++ b/docs/fields/upload.mdx @@ -6,18 +6,13 @@ desc: Upload fields will allow a file to be uploaded, only from a collection sup keywords: upload, images media, fields, config, configuration, documentation, Content Management System, cms, headless, javascript, node, react, nextjs --- - - The Upload field allows for the selection of a Document from a collection supporting Uploads, and - formats the selection as a thumbnail in the Admin Panel. - +The Upload Field allows for the selection of a Document from a Collection supporting [Uploads](../upload/overview), and formats the selection as a thumbnail in the Admin Panel. - - Important: -
- To use this field, you need to have a Collection configured to allow Uploads. For more - information, [click here](/docs/upload/overview) to read about how to enable Uploads on a - collection by collection basis. - +Upload fields are useful for a variety of use cases, such as: + +- To provide a `Page` with a featured image +- To allow for a `Product` to deliver a downloadable asset like PDF or MP3 +- To give a layout building block the ability to feature a background image -**Example uses:** +To create an Upload Field, set the `type` to `upload` in your [Field Config](./overview): -- To provide a `Page` with a featured image -- To allow for a `Product` to deliver a downloadable asset like PDF or MP3 -- To give a layout building block the ability to feature a background image +```ts +import type { Field } from 'payload/types' -## Config +export const MyUploadField: Field = { + // ... + // highlight-start + type: 'upload', + relationTo: 'media', + // highlight-end +} +``` + + + Important: + To use the Upload Field, you must have a [Collection](../configuration/collections) configured to allow [Uploads](../upload/overview). + + +## Config Options | Option | Description | | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -51,7 +59,7 @@ keywords: upload, images media, fields, config, configuration, documentation, Co | **`defaultValue`** | Provide data to be used for this field's default value. [More](/docs/fields/overview#default-values) | | **`localized`** | Enable localization for this field. Requires [localization to be enabled](/docs/configuration/localization) in the Base config. | | **`required`** | Require this field to have a value. | -| **`admin`** | Admin-specific configuration. See the [default field admin config](/docs/fields/overview#admin-config) for more details. | +| **`admin`** | Admin-specific configuration. [Admin Options](../admin/fields#admin-options). | | **`custom`** | Extension point for adding custom data (e.g. for plugins) | | **`typescriptSchema`** | Override field type generation with providing a JSON schema | diff --git a/docs/getting-started/installation.mdx b/docs/getting-started/installation.mdx index c88825864..3e61fa77a 100644 --- a/docs/getting-started/installation.mdx +++ b/docs/getting-started/installation.mdx @@ -79,6 +79,8 @@ app/ ├── // Your app files ``` +_For an exact reference of the `(payload)` directory, see [Project Structure](../admin/overview#project-structure)._ + You may need to copy all of your existing frontend files, including your existing root layout, into its own newly created [Route Group](https://nextjs.org/docs/app/building-your-application/routing/route-groups), i.e. `(my-app)`. diff --git a/docs/getting-started/what-is-payload.mdx b/docs/getting-started/what-is-payload.mdx index 2d946897b..0c26b915a 100644 --- a/docs/getting-started/what-is-payload.mdx +++ b/docs/getting-started/what-is-payload.mdx @@ -28,7 +28,7 @@ No matter what you're building, Payload will give you backend superpowers. It ca ### Open source - deploy anywhere, including Vercel -It's fully open source with an MIT license and you can self-host anywhere that you can run a Node app. You can also deploy serverless to hosts like Vercel, right inside your existing Next.js app folder. +It's fully open source with an MIT license and you can self-host anywhere that you can run a Node.js app. You can also deploy serverless to hosts like Vercel, right inside your existing Next.js application. ### Code-first and version controlled