Skip to content
KeystoneJS LogoKeystoneJS (α)

createList(name, options)

Usage

keystone.createList('Post', {
  /* ...config */
});

Config

OptionTypeDefaultDescription
fieldsObjectDefines the fields in a list.
schemaDocStringA description for the list. Used in the Admin UI.
hooksObject{}Specify hooks to execute functions after list actions.
labelFieldStringnameSpecify a field to use as a label for individual list items.
labelResolverFunctionResolves labelField or idFunction to resolve labels for individual list items.
accessFunction | Object | BooleantrueAccess control options for the list.
adapterConfigObjectOverride the adapter config options for a specific list.
itemQueryNameStringChanges the item name in GraphQL queries and mutations.
listQueryNameStringChanges the list name in GraphQL queries and mutations.
singularStringSpecify a singular noun for Keystone to use for the list.
pluralStringSpecify a plural for Keystone to use for the list.
pathStringChanges the path in the Admin UI.
pluginsArray[]An array of plugins that can modify the list config.

fields

Defines the fields to use in a list.

Usage

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

See: Fields for more information on configuring field options.

schemaDoc

A description for the list used in the GraphQL schema.

hooks

Specify hooks to execute functions after list actions. List actions include:

  • resolveInput
  • validateInput
  • beforeChange
  • afterChange
  • beforeDelete
  • validateDelete
  • afterDelete

Usage

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

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.

Usage

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.

Usage

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

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)[https://v5.keystonejs.com/api/access-control] for more details.

Usage

keystone.createList('User', {
  fields: {
    name: { type: Text },
  },
  access: {
    read: false,
  },
});

adminConfig

Options for the AdminUI including:

  • defaultPageSize
  • defaultColumns
  • defaultSort
  • maximumPageSize

Usage

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

itemQueryName

Changes the item name in GraphQL queries and mutations.

Usage

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
  }
}

listQueryName

Changes the list name in GraphQL queries and mutations.

Usage

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

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

query {
  allPeople {
    name
  }
}

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.

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',
});

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.

adapterConfig

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

const keystone = new Keystone({
  name: 'my-project',
  adapter: new Adapter({
    /* ...adapterConfig */
  }),
});

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

plugins

An array of functions that modify config values. Plugin functions receive a config object and can modify or extend this. They should return a valid list config.

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.

queryLimits

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

  • maxResults: maximum number of results that can be returned in a query (or subquery)
keystone.createList('Post', {
  fields: {
    title: { type: Text },
  },
  queryLimits: {
    maxResults: 100,
  },
});

Have you found a mistake, something that is missing, or could be improved on this page? Please edit the Markdown file on GitHub and submit a PR with your changes.

Edit Page