Fields

We recently improved this API. If you were using it prior to October 5th 2021, read this guide for details on how to upgrade.

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, list } from '@keystone-6/core';
import {
  // Scalar types
  checkbox,
  integer,
  bigInt,
  json,
  float,
  decimal,
  password,
  select,
  multiselect,
  text,
  timestamp,
  calendarDay,

  // Relationship type
  relationship,

  // Virtual type
  virtual,

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

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

export default config({
  lists: {
    SomeListName: list({
      fields: {
        someFieldName: text({ /* ... */ }),
        /* ... */
      },
    }),
    /* ... */
  },
  /* ... */
});

Common configuration

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

Options:

• isFilterable (default: true): If false, the GraphQL API and admin UI will not support filtering by this field. If true (default), the GraphQL API and Admin UI will support filtering by this field. If a function is provided, it will be evaluated dynamically each time this field is used as a filter in a GraphQL operation. If the function returns false, the operation will return an error indicating that filtering on this field is not allowed.
• isOrderable (default: true): If false, the GraphQL API and admin UI will not support ordering by this field. If true (default), the GraphQL API and Admin UI will support ordering by this field. If a function is provided, it will be evaluated dynamically each time this field is used as an ordering field in a GraphQL operation. If the function returns false, the operation will return an error indicating this ordering by this field is not allowed.
• 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 module path that is resolved from where keystone start is run, resolving to a module containing code to replace or extend the Admin UI components for this field. See the Custom Field Views guide for details on how to use this option.
  • createView.fieldMode (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, context } that returns one of ['edit', 'hidden']. Defaults to the list's ui.createView.defaultFieldMode config if defined. See the Lists API for details.
  • itemView.fieldMode (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, context, item } that returns one of ['edit', 'read', 'hidden']. Defaults to the list's ui.itemView.defaultFieldMode config if defined. See the Lists API for details.
  • listView.fieldMode (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, context } that returns one of ['read', 'hidden']. Defaults to the list's ui.listView.defaultFieldMode config if defined. See the Lists API for details.
• graphql: Configures certain aspects of the GraphQL API.
  • cacheHint (default: undefined): Allows you to specify the dynamic cache control hints used for queries to this list.
  • omit (default: 'undefined'): Controls whether this field appears in the autogenerated types of the GraphQL API This option accepts either true, or an array of the values read, create, or update. If you specify true then the field will be excluded from all input and output types in the GraphQL API. If you provide an array of read, create, or update the field will be omitted from the corresponding input and output types in the GraphQL API.

export default config({
  lists: {
    SomeListName: list({
      fields: {
        someFieldName: text({
          isFilterable: ({ context, session, fieldKey, listKey }) => true,
          isOrderable: ({ context, session, fieldKey, listKey }) => true,
          access: { /* ... */ },
          hooks: { /* ... */ },
          label: '...',
          ui: {
            views: './path/to/viewsModule',
            createView: {
              fieldMode: ({ session, context }) => 'edit',
            },
            itemView: {
              fieldMode: ({ session, context, item }) => 'read',
            },
            listView: {
              fieldMode: ({ session, context }) => 'read',
            },
          },
          graphql: {
            cacheHint: { maxAge: 60, scope: CacheScope.Private },
            omit: ['read', 'create', 'update'],
          }
        }),
        /* ... */
      },
    }),
    /* ... */
  },
  /* ... */
});

Scalar types

• BigInt
• Calendar Day
• Checkbox
• Decimal
• Float
• Integer
• JSON
• Multiselect
• Password
• Select
• Text
• Timestamp

Relationship type

• Relationship

Virtual type

• Virtual

File types

• File
• Image

Complex types

• Document
• Cloudinary Image

Related resources