Skip to Page NavigationSkip to Page NavigationSkip to Content
Keystone 6 is in Community Preview! What does that mean? see our Roadmap. For Keystone 5 docs, visit v5.keystonejs.com
Keystone 6preview
Why KeystoneUpdatesDocsGet Started

Fields API

The fields option of a list configuration defines the names, types, and configuration of the fields in the list. This configuration option takes an object with field names as keys, and configured field types as values.

This document covers the different field types which are available and the configuration options they accept. To see how to access fields in the GraphQL API please see the GraphQL API docs.

import { config, createSchema, list } from '@keystone-next/keystone/schema';
import {
  // Scalar types
  checkbox,
  integer,
  json,
  float,
  password,
  select,
  text,
  timestamp,


  // Relationship type
  relationship,


  // Index types
  autoIncrement,


  // Virtual type
  virtual,


  // File types
  file,
  image,
} from '@keystone-next/fields';


// Complex types
import { document } from '@keystone-next/fields-document';
import { cloudinaryImage } from '@keystone-next/cloudinary';


export default config({
  lists: createSchema({
    ListName: list({
      fields: {
        fieldName: text({ /* ... */ }),
        /* ... */
      },
    }),
    /* ... */
  }),
  /* ... */
});

Common configuration

All field types accept a common set of configuration options. All options are optional.

Options:

  • access: Defines the Access Control rules for the field. See the Access Control API for full details on the available access control options.
  • hooks: The hooks option defines hook functions for the field. Hooks allow you to execute code at different stages of the mutation lifecycle. See the Hooks API for full details on the available hook options.
  • label: The label displayed for this field in the Admin UI. Defaults to a human readable version of the field name.
  • ui: Controls how the field is displayed in the Admin UI.
    • views: A resolved path to a module containing code to replace or extend the default Admin UI components for this field. See the Custom Field Views guide for details on how to use this option.
    • createView (default: 'edit'): Controls the create view page of the Admin UI. Can be one of ['edit', 'hidden'], or an async function with an argument { session } that returns one of ['edit', 'hidden']. Defaults to the list's ui.createView.defaultFieldMode config if defined. See the Schema API for details.
    • itemView (default: 'edit'): Controls the item view page of the Admin UI. Can be one of ['edit', 'read', 'hidden'], or an async function with an argument { session, item } that returns one of ['edit', 'read', 'hidden']. Defaults to the list's ui.itemView.defaultFieldMode config if defined. See the Schema API for details.
    • listView (default: 'read'): Controls the list view page of the Admin UI. Can be one of ['read', 'hidden'], or an async function with an argument { session } that returns one of ['read', 'hidden']. Defaults to the list's ui.listView.defaultFieldMode config if defined. See the Schema API for details.
  • graphql: Configures certain aspects of the GraphQL API.
export default config({
  lists: createSchema({
    ListName: list({
      fields: {
        fieldName: text({
          access: { /* ... */ },
          hooks: { /* ... */ },
          label: '...',
          ui: {
            views: require.resolve('path/to/viewsModule.tsx'),
            createView: {
              fieldMode: ({ session }) => 'edit',
            },
            itemView: {
              fieldMode: ({ session, item }) => 'read',
            },
            listView: {
              fieldMode: ({ session }) => 'read',
            },
          },
          graphql: {
            cacheHint: { maxAge: 60, scope: CacheScope.Private }
          }
        }),
        /* ... */
      },
    }),
    /* ... */
  }),
  /* ... */
});

Scalar types

checkbox

A checkbox field represents a boolean (true/false) value.

Options:

  • defaultValue (default: undefined): Can be either a boolean value or an async function which takes an argument ({ context, originalInput }) and returns a boolean value. This value will be used for the field when creating items if no explicit value is set. context is a KeystoneContext object. originalInput is an object containing the data passed in to the create mutation.
  • isRequired (default: false): If true then this field can never be set to null.
import { config, createSchema, list } from '@keystone-next/keystone/schema';
import { checkbox } from '@keystone-next/fields';


export default config({
  lists: createSchema({
    ListName: list({
      fields: {
        fieldName: checkbox({
          defaultValue: true,
          isRequired: true,
        }),
        /* ... */
      },
    }),
    /* ... */
  }),
  /* ... */
});

integer

An integer field represents an integer value.

Options:

  • defaultValue (default: undefined): Can be either an integer value or an async function which takes an argument ({ context, originalInput }) and returns an integer value. This value will be used for the field when creating items if no explicit value is set. context is a KeystoneContext object. originalInput is an object containing the data passed in to the create mutation.
  • isRequired (default: false): If true then this field can never be set to null.
  • isUnique (default: false): If true then all values of this field must be unique. This will also allow you to uniquely filter by this field in the GraphQL API.
import { config, createSchema, list } from '@keystone-next/keystone/schema';
import { integer } from '@keystone-next/fields';


export default config({
  lists: createSchema({
    ListName: list({
      fields: {
        fieldName: integer({
          defaultValue: 0,
          isRequired: true,
          isUnique: true,
        }),
        /* ... */
      },
    }),
    /* ... */
  }),
  /* ... */
});

json

A json field represents a JSON blob. Currently the json field is non-orderable and non-filterable.

  • isRequired (default: false): If true then this field can never be set to null.
import { config, createSchema, list } from '@keystone-next/keystone/schema';
import { json } from '@keystone-next/fields';


export default config({
  lists: createSchema({
    ListName: list({
      fields: {
        fieldName: json({
          isRequired: true,
        }),
        /* ... */
      },
    }),
    /* ... */
  }),
  /* ... */
});

float

A float field represents a floating point value.

Options:

  • defaultValue (default: undefined): Can be either a float value or an async function which takes an argument ({ context, originalInput }) and returns a float value. This value will be used for the field when creating items if no explicit value is set. context is a KeystoneContext object. originalInput is an object containing the data passed in to the create mutation.
  • isRequired (default: false): If true then this field can never be set to null.
  • isUnique (default: false): If true then all values of this field must be unique.
import { config, createSchema, list } from '@keystone-next/keystone/schema';
import { float } from '@keystone-next/fields';


export default config({
  lists: createSchema({
    ListName: list({
      fields: {
        fieldName: float({
          defaultValue: 3.14159,
          isRequired: true,
          isUnique: true,
        }),
        /* ... */
      },
    }),
    /* ... */
  }),
  /* ... */
});

decimal

A decimal field represents a decimal value.

Options:

  • defaultValue (default: undefined): Can be either a decimal value or an async function which takes an argument ({ context, originalInput }) and returns a decimal value. This value will be used for the field when creating items if no explicit value is set. context is a KeystoneContext object. originalInput is an object containing the data passed in to the create mutation.
  • precision (default: 18): Maximum number of digits that are present in the number.
  • scale (default: 4): Maximum number of decimal places.
  • isRequired (default: false): If true then this field can never be set to null.
  • isUnique (default: false): If true then all values of this field must be unique.
import { config, createSchema, list } from '@keystone-next/keystone/schema';
import { decimal } from '@keystone-next/fields';


export default config({
  lists: createSchema({
    ListName: list({
      fields: {
        fieldName: decimal({
          defaultValue: 3.142,
          precision: 12,
          scale: 3,
          isRequired: true,
          isUnique: true,
        }),
        /* ... */
      },
    }),
    /* ... */
  }),
  /* ... */
});

password

A password field represents an encrypted password value.

Options:

  • isRequired (default: false): If true then this field can never be set to null.
  • minLength (default: 8): The minimum length password accepted.
  • rejectCommon (default: false): Rejects passwords from a list of commonly used passwords.
  • bcrypt (default: require('bcryptjs')): A module which implements the same interface as the bcryptjs package, such as the native bcrypt package. This module will be used for all encryption routines in the password field.
import { config, createSchema, list } from '@keystone-next/keystone/schema';
import { password } from '@keystone-next/fields';


export default config({
  lists: createSchema({
    ListName: list({
      fields: {
        fieldName: password({
          isRequired: true,
          minLength: 10,
          rejectCommon: true,
          bcrypt: require('bcrypt'),
        }),
        /* ... */
      },
    }),
    /* ... */
  }),
  /* ... */
});

select

A select field represents the selection of one of fixed set of values. Values can be either strings, integers, or enum values, as determined by the dataType option. This will determine their GraphQL data type, as well as their database storage type.

Options:

  • dataType (default: 'string'): Sets the type of the values of this field. Must be one of ['string', 'enum', 'integer'].
  • options: An array of { label, value }. label is a string to be displayed in the Admin UI. value is either a string (for { dataType: 'string' } or { dataType: 'enum' }), or a number (for { dataType: 'integer' }). The value will be used in the GraphQL API and stored in the database.
  • defaultValue: (default: undefined): Can be either a string/integer value or an async function which takes an argument ({ context, originalInput }) and returns a string/integer value. This value will be used for the field when creating items if no explicit value is set, and must be one of the values defined in options. context is a KeystoneContext object. originalInput is an object containing the data passed in to the create mutation.
  • isRequired (default: false): If true then this field can never be set to null.
  • isUnique (default: false): If true then all values of this field must be unique.
  • ui (default: { displayMode: 'select' }): Configures the display mode of the field in the Admin UI. Can be one of ['select', 'segmented-control'].
import { config, createSchema, list } from '@keystone-next/keystone/schema';
import { select } from '@keystone-next/fields';


export default config({
  lists: createSchema({
    ListName: list({
      fields: {
        fieldName: select({
          dataType: 'enum',
          options: [
            { label: '...', value: '...' },
            /* ... */
          ],
          defaultValue: '...',
          isRequired: true,
          isUnique: true,
          ui: { displayMode: 'select' },
        }),
        /* ... */
      },
    }),
    /* ... */
  }),
  /* ... */
});

text

A text field represents a string value.

Options:

  • defaultValue (default: undefined): Can be either a string value or an async function which takes an argument ({ context, originalInput }) and returns a string value. This value will be used for the field when creating items if no explicit value is set. context is a KeystoneContext object. originalInput is an object containing the data passed in to the create mutation.
  • isRequired (default: false): If true then this field can never be set to null.
  • isUnique (default: false): If true then all values of this field must be unique. This will also allow you to uniquely filter by this field in the GraphQL API.
  • ui (default: { displayMode: 'input' }): Configures the display mode of the field in the Admin UI. Can be one of ['input', 'textarea'].
import { config, createSchema, list } from '@keystone-next/keystone/schema';
import { text } from '@keystone-next/fields';


export default config({
  lists: createSchema({
    ListName: list({
      fields: {
        fieldName: text({
          defaultValue: '...',
          isRequired: true,
          isUnique: true,
          ui: { displayMode: 'textarea' },
        }),
        /* ... */
      },
    }),
    /* ... */
  }),
  /* ... */
});

timestamp

A timestamp field represents a time value in ISO8601 format.

Options:

  • defaultValue (default: undefined): Can be either a string value or an async function which takes an argument ({ context, originalInput }) and returns a string value. The string value must be an ISO8601 formatted timestamp string, e.g. '1970-01-01T00:00:00.000Z'. This value will be used for the field when creating items if no explicit value is set. context is a KeystoneContext object. originalInput is an object containing the data passed in to the create mutation.
  • isRequired (default: false): If true then this field can never be set to null.
  • isUnique (default: false): If true then all values of this field must be unique.
import { config, createSchema, list } from '@keystone-next/keystone/schema';
import { timestamp } from '@keystone-next/fields';


export default config({
  lists: createSchema({
    ListName: list({
      fields: {
        fieldName: timestamp({
          defaultValue: '1970-01-01T00:00:00.000Z',
          isRequired: true,
          isUnique: true,
        }),
        /* ... */
      },
    }),
    /* ... */
  }),
  /* ... */
});

Relationship type

relationship

A relationship field represents a relationship between two lists.

Read our relationships guide for details on Keystone’s relationship model and how to configure them in your project.

  • ref (required): A string of the form <listKey> or <listKey>.<fieldPath>.
  • many (default: false): Configures the cardinality of the relationship.
  • defaultValue (default: undefined): Can be either a relationship input value or an async function which takes an argument ({ context, originalInput }) and returns a relationship input value. This value will be used for the field when creating items if no explicit value is set. context is a KeystoneContext object. originalInput is an object containing the data passed in to the create mutation.
  • ui (default: { hideCreate: false, displayMode: 'select' }): Configures the display mode of the field in the Admin UI.
    • hideCreate (default: false). If true, the "Create related item" button is not shown in the item view.
    • displayMode (default: 'select'): Controls the mode used to display the field in the item view. The mode 'select' displays related items in a select component, while 'cards' displays the related items in a card layout. Each display mode supports further configuration.
  • ui.displayMode === 'select' options:
    • labelField: The field path from the related list to use for item labels in the select. Defaults to the labelField configured on the related list.
  • ui.displayMode === 'cards' options:
    • cardFields: A list of field paths from the related list to render in the card component. Defaults to 'id' and the labelField configured on the related list.
    • linkToItem (default false): If true, the default card component will render as a link to navigate to the related item.
    • removeMode (default: 'disconnect'): Controls whether the Remove button is present in the card. If 'disconnect', the button will be present. If 'none', the button will not be present.
    • inlineCreate (default: null): If not null, an object of the form { fields: [...] }, where fields is a list of field paths from the related list should be provided. An inline Create button will be included in the cards allowing a new related item to be created based on the configured field paths.
    • inlineEdit (default: null): If not null, an object of the form { fields: [...] }, where fields is a list of field paths from the related list should be provided. An Edit button will be included in each card, allowing the configured fields to be edited for each related item.
    • inlineConnect (default: false): If true, an inline Link existing item button will be present, allowing existing items of the related list to be connected in this field.
  • ui.displayMode === 'count' only supports many relationships
import { config, createSchema, list } from '@keystone-next/keystone/schema';
import { relationship } from '@keystone-next/fields';


export default config({
  lists: createSchema({
    ListName: list({
      fields: {
        fieldName: relationship({
          ref: '...',
          many: false,
          defaultValue: '...',
          ui: {
            hideCreate: false,
            // Display mode: 'select'
            displayMode: 'select',
            labelField: 'name',
            // Display mode: 'cards'
            displayMode: 'cards',
            cardFields: [...],
            linkToItem: true,
            removeMode: 'disconnect',
            inlineCreate: { fields: [...] },
            inlineEdit: { fields: [...] },
            inlineConnect: true,
            // Display mode: 'count'
            // requires many: true above
            displayMode: 'count',
           },
        }),
        /* ... */
      },
    }),
    /* ... */
  }),
  /* ... */
});

Index types

autoIncrement

(coming soon)

Options:

  • defaultValue
  • isRequired
  • isUnique
import { config, createSchema, list } from '@keystone-next/keystone/schema';
import { autoIncrement } from '@keystone-next/fields';


export default config({
  lists: createSchema({
    ListName: list({
      fields: {
        fieldName: autoIncrement({
          defaultValue: 0,
          isRequired: true,
          isUnique: true,
        }),
        /* ... */
      },
    }),
    /* ... */
  }),
  /* ... */
});

Virtual type

virtual

A virtual field represents a value which is computed a read time, rather than stored in the database. See the virtual fields guide for details on how to use virtual fields.

Options:

  • field (required): The GraphQL field that defines the type, resolver and arguments.
  • graphQLReturnFragment (default: '' ): The sub-fields that should be fetched by the Admin UI when displaying this field.
import { config, createSchema, list } from '@keystone-next/keystone/schema';
import { virtual } from '@keystone-next/fields';
import { schema } from '@keystone-next/types';


export default config({
  lists: createSchema({
    ListName: list({
      fields: {
        fieldName: virtual({
          field: schema.field({
            type: schema.String,
            args: { something: schema.arg({ type: schema.Int }) },
            resolve(item, args, context, info) {


            }
          })
        }),
        /* ... */
      },
    }),
    /* ... */
  }),
  /* ... */
});

File types

File types allow you to upload different types of files to your Keystone system.

file

A file field represents a file of any type.

See config.files for details on how to configure your Keystone system with support for the file field type.

Options:

  • isRequired (default: false): If true then this field can never be set to null.
import { config, createSchema, list } from '@keystone-next/keystone/schema';
import { file } from '@keystone-next/fields';


export default config({
  lists: createSchema({
    ListName: list({
      fields: {
        repo: file({
          isRequired: true,
        }),
        /* ... */
      },
    }),
    /* ... */
  }),
  /* ... */
});

image

An image field represents an image file, i.e. .jpg, .png, .webp, or .gif.

See config.images for details on how to configure your Keystone system with support for the image field type.

Options:

  • isRequired (default: false): If true then this field can never be set to null.
import { config, createSchema, list } from '@keystone-next/keystone/schema';
import { image } from '@keystone-next/fields';


export default config({
  lists: createSchema({
    ListName: list({
      fields: {
        avatar: image({
          isRequired: true,
        }),
        /* ... */
      },
    }),
    /* ... */
  }),
  /* ... */
});

Complex types

document

(coming soon)

Options:

  • relationships
  • componentBlocks
  • formatting
  • links
  • dividers
  • layouts
import { config, createSchema, list } from '@keystone-next/keystone/schema';
import { document } from '@keystone-next/fields-document';


export default config({
  lists: createSchema({
    ListName: list({
      fields: {
        fieldName: document({
          relationships: { /* ... */ },
          componentBlocks: {
            block: { /* ... */ },
            /* ... */
          },
          formatting: { /* ... */ },
          links: true,
          dividers: true,
          layouts: [/* ... */],
        }),
        /* ... */
      },
    }),
    /* ... */
  }),
  /* ... */
});

cloudinaryImage

(coming soon)

  • isRequired (default: false): If true then this field can never be set to null.
  • cloudinary: Configuration for the connected Cloudinary account.
    • cloudName
    • apiKey
    • apiSecret
    • folder
import { config, createSchema, list } from '@keystone-next/keystone/schema';
import { cloudinaryImage } from '@keystone-next/cloudinary';


export default config({
  lists: createSchema({
    ListName: list({
      fields: {
        fieldName: cloudinaryImage({
          isRequired: true,
          cloudinary: {
            cloudName: process.env.CLOUDINARY_CLOUD_NAME,
            apiKey: process.env.CLOUDINARY_API_KEY,
            apiSecret: process.env.CLOUDINARY_API_SECRET,
            folder: process.env.CLOUDINARY_API_FOLDER,
          },
        }),
        /* ... */
      },
    }),
    /* ... */
  }),
  /* ... */
});

On this page