Configure View Configurations

In this guide, you'll learn how to configure the data tables that use view configurations in the dashboard. You'll learn how to set the default columns and their order, add computed columns, change how a column's value renders, and show a configurable data table in your admin customizations.

How Column Configurations are Generated#

The Settings Module discovers the entities in your application from the registered modules' query graph, including your custom modules' data models. For each entity, it generates the column configurations that are used in its configurable data table in the Medusa Admin dashboard.

You can then override these generated column configurations, as explained in the following sections. You can change the default visible columns, their order, how their values render, and add computed columns.

How to Override Entity Column Configurations#

In the Settings Module's configurations, you can override the generated columns of a core or custom data model. These overrides are applied to the configurable data table in the Medusa Admin dashboard when the view configuration feature is enabled, and only to the system default view configuration.

In this section, you'll learn how to configure the default columns of a custom data model Brand defined in a custom module. You can use the same approach to configure the default columns of any core or custom data model. The sections after this one explain all the different configuration overrides you can set for an entity's columns.

Step 1: Configure the Settings Module#

To override the generated columns of an entity, pass the entityOverrides option to the Settings Module in medusa-config.ts. Its value is an object whose keys are data model names as passed to the MedusaService extended by the module's service, and whose values are the entity's override configuration.

For example:

medusa-config.ts
1module.exports = defineConfig({2  // ...3  modules: [4    {5      resolve: "@medusajs/medusa/settings",6      options: {7        entityOverrides: {8          Brand: {9            defaultVisibleFields: [10              "name",11              "description",12            ],13            defaultFieldOrdering: { name: 100 },14          },15        },16      },17    },18  ],19})

This configuration overrides the default columns of the Brand data model, assuming you defined it in a custom module. The name and description columns are shown by default, and the name column appears first.

Step 2: Show a Configurable Data Table in Your Admin Customizations#

Next, you can show a configurable, view-aware data table for an entity in your admin customizations, such as a custom UI route.

To do that, use the ConfigurableDataTable component with an adapter created by the createTableAdapter utility, both available through the admin dashboard.

For example, create the file src/admin/routes/brands/page.tsx with the following content:

src/admin/routes/brands/page.tsx
1import { defineRouteConfig } from "@medusajs/admin-sdk"2import { ConfigurableDataTable } from "@medusajs/dashboard/components"3import { createTableAdapter } from "@medusajs/dashboard/lib"4import { useQuery } from "@tanstack/react-query"5import { sdk } from "../../lib/sdk"6
7const adapter = createTableAdapter({8  entity: "brand",9  useData: (fields, params) => {10    const { data, isLoading, isError, error } =11      useQuery({12        queryKey: ["brands", fields, params],13        queryFn: () =>14          sdk.client.fetch("/admin/brands", {15            query: { fields, ...params },16          }),17      })18
19    return {20      data: data?.brands,21      count: data?.count,22      isLoading,23      isError,24      error,25    }26  },27  getRowHref: (row) => `/brands/${row.id}`,28})29
30const BrandsPage = () => {31  return (32    <ConfigurableDataTable33      adapter={adapter}34      heading="Brands"35    />36  )37}38
39export const config = defineRouteConfig({40  label: "Brands",41})42
43export default BrandsPage

This API route retrieves the list of brands from the /admin/brands API route and shows them in a configurable data table. The table uses the default columns defined in the Settings Module's configuration, and admin users can customize the columns and save their view configurations.

If you go to /admin/brands in your Medusa Admin dashboard, you'll see the configurable data table for the Brand data model. Based on the configurations you defined in medusa-config.ts, it shows the name and description columns, and the name column appears first. You can customize the configurations, such as the visible columns and their order, and save your view configuration.

Set Default Visible Fields and Ordering#

To set which columns are shown by default and their order, use the following properties in the entity's override configuration:

• defaultVisibleFields: An array of field names that are shown by default, in the order they're listed.
• defaultFieldOrdering: An object whose keys are field names, and whose values are numbers. Columns are ordered by these numbers in ascending order, so a column with a lower number appears first.

For example:

medusa-config.ts
1module.exports = defineConfig({2  // ...3  modules: [4    {5      resolve: "@medusajs/medusa/settings",6      options: {7        entityOverrides: {8          Brand: {9            defaultVisibleFields: ["name", "description"],10            defaultFieldOrdering: {11              name: 100,12              description: 200,13            },14          },15          Product: {16            defaultVisibleFields: ["title", "collection.title"],17            defaultFieldOrdering: {18              title: 100,19              "collection.title": 200,20            },21          },22        },23      },24    },25  ],26})

You override the default columns of the Brand and Product data models. The Brand override shows the name and description columns, and the Product override shows the title column and the title of its collection.

The Product override adds a relation's field to the visible columns: collection.title shows the title of a product's collection as a column. Use a dotted path to reference a scalar field of a related entity, and use the same dotted path as the key in defaultFieldOrdering.

For a core entity like Product, your configuration is merged with the built-in configuration. For a custom data model like Brand, your configuration is the entire configuration.

Default Column Render Modes#

The Settings Module infers how to render each column's value, which is used to decide the column's render mode. The Medusa Admin dashboard defines cell renderers for these render modes, which are used to render the column's value in the configurable data table.

The Settings Module and Medusa Admin dashboard support the following built-in render modes:

How Render Modes are Inferred#

By default, the Settings Module infers how to render a column's value in the following order of precedence:

1. Name checking: It applies the following name checks and assigns the corresponding render mode if the field name matches:
   • *_at / created_at / updated_at / deleted_at → datetime
   • *_date → date
   • *total / *amount / *price / subtotal / tax_total / shipping_total / discount_total → currency
   • *status / state / payment_status / fulfillment_status → status
   • email / *_email → email
   • phone / *_phone → phone
   • *country_code → country_code
   • url / *_url → url
   • thumbnail / avatar / *_image → image
   • id / *_id → id
   • display_id → display_id
   • count / *_count / *quantity → number
   • is_* / has_* / can_* → boolean
   • metadata → json
2. Type checking: If the field name doesn't match any of the above, it checks the field's type and assigns the corresponding render mode:
   • boolean → boolean
   • text → text
   • number → number
   • dateTime → datetime
   • json → json
   • id → id
3. Fallback: If the field name and type don't match any of the above, it defaults to text.

Override Field Render Modes#

To override the inferred render mode of a field, use the fieldRenderModes property. Its value is an object whose keys are field names, and whose values are render modes:

medusa-config.ts
1module.exports = defineConfig({2  // ...3  modules: [4    {5      resolve: "@medusajs/medusa/settings",6      options: {7        entityOverrides: {8          Brand: {9            defaultVisibleFields: ["name", "description", "asset"],10            fieldRenderModes: {11              asset: "image",12            },13          },14        },15      },16    },17  ],18})

In this example, the asset field of the Brand data model is rendered as an image, even if its name and type don't match any of the built-in render modes.

For render modes that require additional configuration through the metadata property, such as country_code, you can set the required configuration in the entity's override configuration:

medusa-config.ts
1module.exports = defineConfig({2  // ...3  modules: [4    {5      resolve: "@medusajs/medusa/settings",6      options: {7        entityOverrides: {8          Brand: {9            defaultVisibleFields: ["name", "description", "country"],10            fieldRenderModes: {11              country: "country_code",12            },13            fieldMetadata: {14              country: { country_code_field: "country" },15            },16          },17        },18      },19    },20  ],21})

In this example, the country field of the Brand data model is rendered as a country flag, and the country_code_field metadata is set to the same field name.

Define a Custom Render Mode#

In your admin dashboard customization, you can define a custom render mode to render a column's value in a specific way. You can then use that render mode in the entity's override configuration to render a column's value with your custom logic.

Cell renderers are defined in the src/admin/lib/cell-renderers.tsx file of your Medusa project. You can define multiple cell renderers in this file, each defined with the defineCellRenderer utility.

For example, create the file src/admin/lib/cell-renderers.tsx with the following content:

src/admin/lib/cell-renderers.tsx
1import { defineCellRenderer } from "@medusajs/dashboard/lib"2
3defineCellRenderer("capitalized", {4  render: (value) => {5    if (!value) {6      return "-"7    }8
9    const text = String(value)10    return text.charAt(0).toUpperCase() + text.slice(1)11  },12})

In this example, the capitalized render mode capitalizes the first letter of the column's value.

The defineCellRenderer utility accepts the following parameters:

1. A string that is the render mode's name, which you can use in the entity's override configuration.
2. A configuration object with the following properties:
   • render: A function that returns the content of the cell. It receives the following parameters:
     1. The column's value. For regular columns, this is the value of the field. For computed columns, this is the full row.
     2. The full row of data, which includes all the fields of the entity.
     3. The column's configuration as an AdminColumn object, including properties like id, name, field (the field path), data_type, render_mode, and metadata. For computed columns, it also has a computed object with type, required_fields, and optional_fields.
     4. A translation function to translate strings in the cell's content.
   • align: (optional) The alignment of the cell's content. Its value can be left, center, or right. The default value is left.
   • truncateTooltip: (optional) Whether to show a tooltip with the full content when the cell's content is truncated. The default value is true.

You can then apply the capitalized render mode to a regular field in the Brand entity's override configuration using the fieldRenderModes property:

medusa-config.ts
1module.exports = defineConfig({2  // ...3  modules: [4    {5      resolve: "@medusajs/medusa/settings",6      options: {7        entityOverrides: {8          Brand: {9            fieldRenderModes: {10              name: "capitalized",11            },12          },13        },14      },15    },16  ],17})

This applies the capitalized render mode to the name column, so a brand's name renders with its first letter capitalized. Because the renderer only uses the column's own value, no other fields need to be fetched.

Use Metadata in a Custom Render Mode#

A custom render mode can accept configuration through the column's metadata, which makes the render mode reusable across fields. Set the metadata for a regular field with the fieldMetadata property, and read it in the renderer from the third parameter's metadata property.

For example, add a truncated render mode that shortens a value to a maximum length:

src/admin/lib/cell-renderers.tsx
1import { defineCellRenderer } from "@medusajs/dashboard/lib"2
3defineCellRenderer("truncated", {4  render: (value, _row, column) => {5    if (!value) {6      return "-"7    }8
9    const maxLength = column.metadata?.max_length ?? 5010    const text = String(value)11
12    return text.length > maxLength13      ? `${text.slice(0, maxLength)}...`14      : text15  },16})

Then apply the truncated render mode to a regular field and pass its configuration with the fieldMetadata property:

medusa-config.ts
1module.exports = defineConfig({2  // ...3  modules: [4    {5      resolve: "@medusajs/medusa/settings",6      options: {7        entityOverrides: {8          Brand: {9            fieldRenderModes: {10              description: "truncated",11            },12            fieldMetadata: {13              description: { max_length: 50 },14            },15          },16        },17      },18    },19  ],20})

This applies the truncated render mode to the description column and truncates its value to 50 characters. The renderer reads max_length from the column's metadata, which is populated from the fieldMetadata property. You can reuse the same render mode on other fields with a different max_length.

Add Computed Columns#

A computed column is a column whose value is computed from other fields or with custom logic, rather than a direct property of the entity. For example, you can add a products_count column for the Brand data model that shows the number of products associated with a brand.

To add computed columns to an entity's data table, use the computedColumns property on the entity's override configuration. Its value is an array of objects, each having the following properties:

• id: The column's unique identifier.
• name: The column's display name.
• context: (optional) When to use the column. Its value can be display to show the column, filter to only allow filtering by it, or both. The default value is display.
• renderMode: How the column's value renders. This is required for columns with context: display (the default). Its value can either be a built-in render mode or a custom render mode.
• requiredFields: An array of fields needed to compute the column's value.
• metadata: An object of additional configuration for the column, which are used by the render mode's cell renderer. For example, the count render mode uses the metadata.list_field property to count the items in a relation.

For example:

medusa-config.ts
1module.exports = defineConfig({2  // ...3  modules: [4    {5      resolve: "@medusajs/medusa/settings",6      options: {7        entityOverrides: {8          Brand: {9            computedColumns: [10              {11                id: "products_count",12                name: "Product Count",13                renderMode: "count",14                requiredFields: ["products.id"],15                metadata: { list_field: "products" },16              },17            ],18          },19        },20      },21    },22  ],23})

This adds a products_count column to the Brand's configurable data table that shows the number of products associated with a brand, assuming there's a link between them.

The count render mode counts the items in the relation set by metadata.list_field (products here), whereas requiredFields only ensures that relation is fetched onto the row.