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,
  float,
  password,
  select,
  text,
  timestamp,

  // Relationship type
  relationship,

  // Index types
  autoincrement,
  mongoId,

  // Virtual type
  virtual,
} from '@keystone-next/fields';

// Complex types
import { document } from '@keystone-next/fields-document';
import { cloudinary } 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: (coming soon)
- description: (coming soon)
- createView: (coming soon)
- listView: (coming soon)
- itemView: (coming soon)

export default config({
  lists: createSchema({
    ListName: list({
      fields: {
        fieldName: text({
          access: { /* ... */ },
          hooks: { /* ... */ },
          label: '...',
          ui: {
            views: '...',
            description: '...',
            createView: {
              fieldMode: ({ session }) => 'edit',
            },
            listView: {
              fieldMode: ({ session }) => 'read',
            },
            itemView: {
              fieldMode: ({ session, item }) => 'read',
            },
          },
        }),
        /* ... */
      },
    }),
    /* ... */
  }),
  /* ... */
});

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, originalItem }) 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. originalItem 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, originalItem }) 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. originalItem 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.
isIndexed (knex and mongoose adapters only. Default: false): If true a database level index will be applied to this field, which can make searching faster.
isUnique (default: false): If true then all values of this field must be unique.

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,
          isIndexed: true,
          isUnique: 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, originalItem }) 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. originalItem 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.
isIndexed (knex and mongoose adapters only. Default: false): If true a database level index will be applied to this field, which can make searching faster.
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,
          isIndexed: 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.
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,
          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, originalItem }) 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. originalItem 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.
isIndexed (knex and mongoose adapters only. Default: false): If true a database level index will be applied to this field, which can make searching faster.
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,
          isIndexed: 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, originalItem }) 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. originalItem 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.
isIndexed (knex and mongoose adapters only. Default: false): If true a database level index will be applied to this field, which can make searching faster.
isUnique (default: false): If true then all values of this field must be unique.
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,
          isIndexed: true,
          isUnique: true,
          ui: { displayMode: 'textarea' },
        }),
        /* ... */
      },
    }),
    /* ... */
  }),
  /* ... */
});

timestamp

A timestamp field represents a time value.

Options:

defaultValue (default: undefined): Can be either a string value or an async function which takes an argument ({ context, originalItem }) 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. originalItem 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.
isIndexed (knex and mongoose adapters only. Default: false): If true a database level index will be applied to this field, which can make searching faster.
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,
          isIndexed: true,
          isUnique: true,
        }),
        /* ... */
      },
    }),
    /* ... */
  }),
  /* ... */
});

Relationship type

relationship

A relationship field represents a relationship between two lists.

(coming soon)

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,
          ui: { /* ... */ },
          defaultValue: '...',
          isIndexed: '...',
          isUnique: '...',
        }),
        /* ... */
      },
    }),
    /* ... */
  }),
  /* ... */
});

Index types

autoincrement

(coming soon)

Options:

defaultValue
isRequired
isIndexed (knex and mongoose adapters only)
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,
          isIndexed: true,
          isUnique: true,
        }),
        /* ... */
      },
    }),
    /* ... */
  }),
  /* ... */
});

mongoId

(coming soon)

Options:

defaultValue
isRequired
isIndexed (knex and mongoose adapters only)
isUnique

import { config, createSchema, list } from '@keystone-next/keystone/schema';
import { mongoId } from '@keystone-next/fields';

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

Virtual type

virtual

A virtual field represents a value which is computed a read time, rather than stored in the database.

(coming soon)

Options:

resolver (required):
graphQLReturnType (required):
graphQLReturnFragment (default: undefined ):
extendGraphQLTypes (default: []):
args (default: []):

import { config, createSchema, list } from '@keystone-next/keystone/schema';
import { virtual } from '@keystone-next/fields';

export default config({
  lists: createSchema({
    ListName: list({
      fields: {
        fieldName: virtual({
          resolver: (item, args, context, info) => `/* ... */`,
          graphQLReturnType: '...',
          graphQLReturnFragment: '...',
          extendGraphQLTypes: ['...'],
          args: [
            { name: '...', type: 'String' },
            /* ... */
          ],
        }),
        /* ... */
      },
    }),
    /* ... */
  }),
  /* ... */
});

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: [/* ... */],
        }),
        /* ... */
      },
    }),
    /* ... */
  }),
  /* ... */
});

cloudinary

(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 { cloudinary } from '@keystone-next/cloudinary';

export default config({
  lists: createSchema({
    ListName: list({
      fields: {
        fieldName: cloudinary({
          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,
          },
        }),
        /* ... */
      },
    }),
    /* ... */
  }),
  /* ... */
});

Keystone Next
preview

Fields API

Common configuration

Scalar types

checkbox

integer

float

password

select

text

timestamp

Relationship type

relationship

Index types

autoincrement

mongoId

Virtual type

virtual

Complex types

document

cloudinary

On this page

.css-ykpqp6{display:block;position:relative;}.css-ykpqp6:hover a,.css-ykpqp6:focus-within a{opacity:1;}Fields API

On this page

Fields API