Creating lists

Keystone lists define your application's models. These models represent the entities of your application domain and map to the tables in your database.

keystone.createList('ListKey', {...});

Config

Definitions

access

Access control options for the list.

Options for create, read, update and delete - can be a function, GraphQL where clause or Boolean. See the access control API documentation for more details.

adapterConfig

Override the adapter config options for a specific list. Normally adapterConfig is provided when initialising Keystone:

const keystone = new Keystone({
  adapter: new Adapter({...}),
});

Specifying an adapter config on a list item will extend the default config for this list.

adminConfig

Options for the AdminUI including:

• defaultPageSize
• defaultColumns
• defaultSort
• maximumPageSize

keystone.createList('User', {
  fields: {
    name: { type: Text },
    email: { type: Text },
  },
  adminConfig: {
    defaultColumns: 'name,email',
    defaultPageSize: 50,
    defaultSort: 'email',
    maximumPageSize: 100,
  },
});

adminDoc

A description for the list used in the Admin UI. To document the list in the GraphQL schema, see schemaDoc;

keystone.createList('Todo', {
  adminDoc: 'A list of things which need to be done.',
});

fields

Defines the fields to use in a list.

keystone.createList('Post', {
  fields: {
    title: { type: Text },
  },
});

See: Fields for more information on configuring field options.

hooks

Specify functions to be executed during list operations. Supported hooks include:

• Create and update operations
  • resolveInput
  • validateInput
  • beforeChange
  • afterChange
• Delete operations
  • validateDelete
  • beforeDelete
  • afterDelete

See List Hooks in the API docs and the Hooks Guide for details.

Usage

keystone.createList('User', {
  fields: {
    name: { type: Text },
  },
  hooks: {
    resolveInput: ({ resolvedData }) => {
      return {
        name: `${resolvedData.name} the Great!`,
      };
    },
  },
});

itemQueryName

Changes the item name in GraphQL queries and mutations.

keystone.createList('User', {
  fields: {
    name: { type: Text },
  },
  itemQueryName: 'Person',
});

With the above example a GraphQL query might look like this:

query {
  Person(where: { id: "1" }) {
    name
  }
}

label

Overrides label for the list in the AdminUI. Default is listName.

labelField

Specify a field to use as a label for individual list items.

keystone.createList('User', {
  fields: {
    name: { type: Text },
    email: { type: Text },
  },
  labelField: 'name',
});

labelResolver

Function to resolve labels for individual list item. Default resolves the labelField.

keystone.createList('User', {
  fields: {
    name: { type: Text },
    email: { type: Text },
  },
  labelResolver: item => `${item.name} - ${item.email}`,
});

listQueryName

Changes the list name in GraphQL queries and mutations.

keystone.createList('User', {
  fields: {
    name: { type: Text },
  },
  listQueryName: 'People',
});

With the above example a GraphQL query might look like this:

query {
  allPeople {
    name
  }
}

path

Changes the path in the Admin UI. Updating plural and singular values will not change the route in the admin UI. You can specify this using path.

plugins

An array of functions that modify config values. Plugin functions receive (config, { listKey, keystone }), where config is the a list config object, listKey is the name of the list, and keystone is the keystone object. They should return a valid list config. Plugin functions are executed in the order provided in the list, with the output config of one being passed as input to the next. The output of the final plugin is used to construct the List instance.

const setupUserList = ({ fields, ...config }) => {
  return {
    ...config,
    fields: {
      ...fields,
      name: { type: Text },
      password: { type: Password },
    },
  };
};

keystone.createList('User', {
  plugin: [setupUserList],
});

This provides a method for packaging features that can be applied to multiple lists.

plural

Keystone will attempt to determine a plural for list items. Sometimes Keystone will not be able to determine the plural forcing you to change the list name. Or sometimes Keystone may get it wrong, especially for non-English words.

E.g. Keystone thinks the correct plural for Octopus is "Octopi". Everyone knows the scientifically accurate plural is "Octopodes":

keystone.createList('Octopus', {
  fields: {
    legs: { type: Integer },
  },
  plural: 'Octopodes',
});

queryLimits

Configuration for limiting the kinds of queries that can be made against the list, to avoid queries that might overload the server.

See also global query limits on the Keystone object.

• maxResults: maximum number of results that can be returned in a query (or subquery)

keystone.createList('Post', {
  fields: {
    title: { type: Text },
  },
  queryLimits: {
    maxResults: 100,
  },
});

schemaDoc

A description for the list used in the GraphQL schema. To document the list in the Admin UI, see adminDoc;

keystone.createList('Todo', {
  schemaDoc: 'A list of things which need to be done.',
});

singular

Keystone list names should be singular and Keystone will attempt to determine a plural.

Where Keystone can't determine a plural you may be forced to use a different list name.

The singular option allows you to change the display label for singular items.

E.g. Keystone can't determine a plural for 'Sheep'. Let's change the singular option:

keystone.createList('WoolyBoi', {
  fields: {
    sheepName: { type: Text },
  },
  singular: 'Sheep',
  plural: 'Sheep',
});

Note: This will override labels in the AdminUI but will not change graphQL queries. For queries and mutations see: itemQueryName and listQueryName.