LayoutComposer - Admin Components

The LayoutComposer component provides a flexible layout composition system for building admin pages with widget support. It manages the rendering of widgets in specific sections and supports different layout structures.

The LayoutComposer is useful for plugins that want to create custom admin pages with a consistent layout and custom widget injection zones.

Basic Example#

In the following example, the LayoutComposer is used to create a two-column layout for a custom brand details page:

Code
1import { LayoutComposer } from "@medusajs/dashboard/components"2
3const BrandDetailsPage = () => {4  // retrieve brand...5  return (6    <LayoutComposer7      widgetsZonePrefix="brand.details"8      preferredLayoutId="core:two-column"9      data={brand}10      sections={{11        main: (12          <>13            <BrandGeneralSection brand={brand} />14            <BrandVariantsSection brand={brand} />15          </>16        ),17        side: (18          <>19            <BrandMediaSection brand={brand} />20            <BrandStatusSection brand={brand} />21          </>22        ),23      }}24    />25  )26}

The widgetsZonePrefix prop determines the widget injection zones for the page. In this example, the UI route exposes the following zones:

• brand.details: Widgets rendered in the main section of the brand details page.
• brand.details.side: Widgets rendered in the side section of the brand details page.

Single Column Layout#

The LayoutComposer also supports single-column layouts, which is useful for listing pages or pages with a single main content area. For example:

Code
1import { LayoutComposer } from "@medusajs/dashboard/components"2
3const BrandListPage = () => {4  return (5    <LayoutComposer6      widgetsZonePrefix="brand.list"7      preferredLayoutId="core:single-column"8      sections={{9        main: (10          <BrandListSection />11        ),12      }}13    />14  )15}

The widgetsZonePrefix prop determines the widget injection zones for the page. In this example, the UI route exposes the following zone:

• brand.list: Widgets rendered in the main section of the brand list page.

Props#

LayoutComposer.Entry#

Merchants can reorder the sections of a page, and Medusa saves their preference using each entry's component name. Wrap a section in LayoutComposer.Entry with a stable id so that the preference survives renaming or minifying the component.

Code
1import { LayoutComposer } from "@medusajs/dashboard/components"2
3const BrandDetailsPage = () => {4  return (5    <LayoutComposer6      widgetsZonePrefix="brand.details"7      preferredLayoutId="core:two-column"8      sections={{9        main: (10          <>11            <LayoutComposer.Entry id="brand-general">12              <BrandGeneralSection brand={brand} />13            </LayoutComposer.Entry>14            <LayoutComposer.Entry id="brand-variants">15              <BrandVariantsSection brand={brand} />16            </LayoutComposer.Entry>17          </>18        ),19      }}20    />21  )22}

Custom Layouts#

You can create custom layouts by adding a layout file under src/admin/layouts/ in your plugin. A layout file must have a default export (the React component) and a named config export created with defineLayoutConfig.

For example, create the file src/admin/layouts/three-column.tsx with the following content:

src/admin/layouts/three-column.tsx
1import { defineLayoutConfig } from "@medusajs/admin-sdk"2import type {3  LayoutComponentProps,4} from "@medusajs/dashboard/components"5
6const ThreeColumnLayout = ({7  sections,8}: LayoutComponentProps) => (9  <div className="grid grid-cols-3 gap-4">10    <div>{sections.main}</div>11    <div>{sections.side}</div>12    <div>{sections.extra}</div>13  </div>14)15
16export const config = defineLayoutConfig({17  id: "my-plugin:three-column",18  sections: [19    { id: "main", ordering: "list" },20    { id: "side", ordering: "list" },21    { id: "extra", ordering: "list" },22  ],23})24
25export default ThreeColumnLayout

To get type-safe section names when using your custom layout, augment the LayoutSectionRegistry interface in @medusajs/admin-shared:

index.d.ts
1declare module "@medusajs/admin-shared" {2  interface LayoutSectionRegistry {3    "my-plugin:three-column": "main" | "side" | "extra"4  }5}

You can then use the custom layout in the LayoutComposer:

Code
1import { LayoutComposer } from "@medusajs/dashboard/components"2
3const BrandPage = () => {4  return (5    <LayoutComposer6      widgetsZonePrefix="brand.list"7      preferredLayoutId="my-plugin:three-column"8      sections={{9        main: <BrandListSection />,10        side: <BrandFiltersSection />,11        extra: <BrandStatsSection />,12      }}13    />14  )15}