Model configuration

💡

This documentation covers an older version of Next Admin. If you are using the latest version (>=5.0.0 and above), please refer to the current documentation.

To configure your models, you can use the model property of the NextAdmin options parameter.

This property allows you to configure everything about how your models, their fields, their relations are displayed and edited.

Example for a schema with a User, Post and Category model:

import { NextAdminOptions } from "@premieroctet/next-admin";
 
export const options: NextAdminOptions = {
  /* Your other options here */
  model: {
    User: {
      toString: (user) => `${user.name} (${user.email})`,
      title: "Users",
      icon: "UsersIcon",
      list: {
        display: ["id", "name", "email", "posts", "role", "birthDate"],
        search: ["name", "email"],
        filters: [
          {
            name: "is Admin",
            active: false,
            value: {
              role: {
                equals: "ADMIN",
              },
            },
          },
        ],
      },
      edit: {
        display: [
          "id",
          "name",
          "email",
          "posts",
          "role",
          "birthDate",
          "avatar",
        ],
      },
      actions: [
        {
          title: "Send email",
          action: async (model, ids) => {
            const response = await fetch("/api/email", {
              method: "POST",
              body: JSON.stringify(ids),
            });
 
            if (!response.ok) {
              throw new Error("Failed to send email");
            }
          },
          successMessage: "Email sent successfully",
          errorMessage: "Error while sending email",
        },
      ],
    },
    Post: {
      toString: (post) => `${post.title}`,
    },
    Category: {
      title: "Categories",
      icon: "InboxStackIcon",
      toString: (category) => `${category.name}`,
      list: {
        display: ["name", "posts"],
      },
      edit: {
        display: ["name", "posts"],
      },
    },
  },
};

`model`

It takes as key a model name of your schema as value an object to configure it.

By default if no models are defined, they will all be displayed in the admin. If you want more control, you have to define each model individually as empty objects or with the following properties:

Name	Type	Description	Default Value
toString	Function	a function that is used to display your record in related list	id field
aliases	Object	an object containing the aliases of the model fields as keys, and the field name	-
title	String	a string used to display the model name in the sidebar and in the section title	Model name
list	Object	an object containing the list options (see list property)	-
edit	Object	an object containing the edit options (see edit property)	-
actions	Array	an array of actions (see actions property)	-
icon	String	the outline HeroIcon name displayed in the sidebar and pages title	-
permissions	Array	an array to specify restricted permissions on model	-

`list` property

This property determines how your data is displayed in the list view

Name	Type	Description	Default Value
search	Array	an array of searchable fields	All scalar fields are searchable by default
display	Array	an array of fields that are displayed in the list	All scalar fields are displayed by default
fields	Object	an object containing the model fields as keys, and customization values (see fields property)	-
copy	Array	an array of fields that are copyable into the clipboard	undefined - no field is copyable by default
defaultSort	Object	an optional object to determine the default sort to apply on the list	-
defaultSort.field	String	the model's field name to which the sort is applied. It is mandatory	-
defaultSort.direction	String	the sort direction to apply. It is optional	-
filters	Array	define a set of Prisma filters that user can choose in list (see filters)	-
exports	Object	an object or array of export - containing export url (see exports)	-

The search property is only available for scalar fields.

`list.filters` property

The filters property allow you to define a set of Prisma filters that users can apply on the list view. It’s an array of the following object:

Name	Type	Description	Default Value
name	String	a unique name for the filter	-
active	Boolean	a boolean to set the filter active by default	false
value	String	a where clause Prisma filter of the related model (e.g. Prisma operators)	-

`list.exports` property

The exports property allows you to define a set of export actions that users can apply on the list view. It’s an object or an array of objects that can have the following properties:

Name	Type	Description	Default Value
format	String	a string defining the format of the export. It's used to label the export button	undefined
url	String	a string defining the URL of the export action	undefined

The exports property does not account for active filters. If you want to export filtered data, you need to add the filters to the URL or in your export action.

`edit` property

This property determines how your data is displayed in the edit view

Name	Type	Description	Default Value
display	Array	an array of fields that are displayed in the form. It can also be an object that will be displayed in the form of a notice (see notice)	all scalar fields are displayed
styles	Object	an object containing the styles of the form (see styles)	-
fields	Object	an object containing the model fields as keys, and customization values (see fields property)	-
submissionErrorMessage	String	a message displayed if an error occurs during the form submission	'Submission error'

`edit.styles` property

The styles property is available in the edit property.

⚠️

If your options are defined in a separate file, make sure to add the path to the content property of the tailwind.config.js file (see TailwindCSS configuration).

Name	Type	Description
_form	String	a string defining the classname of the form
...	String	all fields of the model, with the field name as the key and the classname as the value

Here is an example of using styles property:

styles: {
  _form: "form-classname",
  ... // all fields
};

`edit.fields` & `list.fields` property

The fields property is available in both list and edit properties.

For the edit property, it can take the following:

Name	Type	Description	Default Value
validate	Function	a function that takes the field value as a parameter, and returns a boolean	-
format	String	a string defining an OpenAPI field format, overriding the one set in the generator. An extra `file` format can be used to be able to have a file input	-
input	React Element	a React Element that should receive CustomInputProps. For App Router, this element must be a client component	-
handler	Object		-
handler.get	Function	a function that takes the field value as a parameter and returns a transformed value displayed in the form	-
handler.upload	Function	an async function that is used only for formats `file` and `data-url`. It takes a Buffer object and an information object containing `name` and `type` properties as parameters and must return a string. It can be useful to upload a file to a remote provider	-
handler.uploadErrorMessage	String	an optional string displayed in the input field as an error message in case of a failure during the upload handler	-
optionFormatter	Function	only for relation fields, a function that takes the field values as a parameter and returns a string. Useful to display your record in related list	-
tooltip	String	A tooltip content to display for the field	-
helperText	String	a helper text that is displayed underneath the input	-
disabled	Boolean	a boolean to indicate that the field is read only	-
display	String	only for relation fields, indicate which display format to use between `list`, `table` or `select`	select
required	Boolean	a true value to force a field to be required in the form, note that if the field is required by the Prisma schema, you cannot set `required` to false	-
relationOptionFormatter	Function	same as `optionFormatter`, but used to format data that comes from an explicit many-to-many relationship	-
orderField	String	the field to use for relationship sorting. This allows to drag and drop the related records in the `list` display	-
relationshipSearchField	String	a field name of the explicit many-to-many relation table to apply the search on. See handling explicit many-to-many	-

Name	Type	Description
formatter	Function	a function that takes the field value as a parameter, and returns a JSX node. It also accepts a second argument which is the NextAdmin context
sortBy	String	available only on many-to-one models. The name of a field in the related model to apply the sort to. Defaults to the id field of the related model

`actions` property

The actions property is an array of objects that allows you to define a set of actions that can be executed on one or more records of the resource. On the list view, there is a default action for deletion. The object can have the following properties:

Name	Type	Description
title	String	action title that will be shown in the action dropdown
action	Function	an async function that will be triggered when selecting the action in the dropdown. For App Router, it must be defined as a server action
successMessage	String	a message that will be displayed when the action is successful
errorMessage	String	a message that will be displayed when the action fails

CustomInputProps type

Represents the props that are passed to the custom input component.

Name	Type	Description
name	String	the field name
value	any	the field value
onChange	Function	a function taking a ChangeEvent as a parameter
readonly	Boolean	boolean indicating if the field is editable or not
rawErrors	Array	array of strings containing the field errors
disabled	Boolean	boolean indicating if the field is disabled

NextAdmin Context type

Represents the context that is passed to the formatter function in the list.fields property.

Name	Type	Description
locale	String	The locale used by the calling page. (refers to the accept-language header)
row	Object	The current row of the list view

Notice type

This type represents the notice object that can be used in the edit property of a model. If you pass a Notice object in the display array, it will be displayed in the form. This can be useful to display alerts or information to the user when editing a record. The object can have the following properties:

Name	Type	Description
title	String	The title of the notice. This is mandatory
id	String	A unique identifier for the notice that can be used to style it with the `styles` property. This is mandatory
description	String	The description of the notice. This is optional

Here is a quick example of usage.

Considering you have a model User with the following configuration:

.../options.ts

export const options: NextAdminOptions = {
  basePath: "/admin",
  title: "⚡️ My Admin",
  model: {
    User: {
      /**
        ...some configuration 
      **/
      edit: {
        display: [
          "id",
          "name",
          {
            title: "Email is mandatory",
            id: "email-notice",
            description: "You must add an email from now on",
          } as const,
          "email",
          "posts",
          "role",
          "birthDate",
          "avatar",
          "metadata",
        ],
        styles: {
          _form: "grid-cols-3 gap-4 md:grid-cols-4",
          id: "col-span-2 row-start-1",
          name: "col-span-2 row-start-1",
          "email-notice": "col-span-4 row-start-3",
          email: "col-span-4 md:col-span-2 row-start-4",
          posts: "col-span-4 md:col-span-2 row-start-5",
          role: "col-span-4 md:col-span-2 row-start-6",
          birthDate: "col-span-3 row-start-7",
          avatar: "col-span-4 row-start-8",
          metadata: "col-span-4 row-start-9",
        },
        /** ... some configuration */
      },
    },
  },
};

In this example, the email-notice notice will be displayed in the form before the email field. Notice example

Model configuration

model

list property

list.filters property

list.exports property

edit property

edit.styles property

edit.fields & list.fields property

actions property