#ProLayout - Advanced Layout

ProLayout provides a standard, yet flexible, middle and backend layout, with one-click layout switching and automatic menu generation. It can be used with PageContainer to automatically generate breadcrumbs, page headers, and provide a low-cost solution to access the footer toolbar.

#When to use

ProLayout can be used to reduce layout costs when content needs to be carried on a page.

#Issue regression scenarios

import {
  CheckCard,
  PageContainer,
  ProCard,
  ProConfigProvider,
  ProLayout,
} from '@ant-design/pro-components';
import { Alert, ConfigProvider, Segmented, Space } from 'antd';
import { useState } from 'react';

const routes = [
  {
    path: '/dashboard',
    name: 'Dashboard',
    children: [
      { path: '/dashboard/analysis', name: 'Analysis' },
      { path: '/dashboard/monitor', name: 'Monitor' },
    ],
  },
  { path: '/settings', name: 'Settings' },
];

export default () => {
  const [navTheme, setNavTheme] = useState<'light' | 'realDark'>('light');

  return (
    <Space direction="vertical" size={16} style={{ width: '100%' }}>
      <Alert
        type="info"
        showIcon
        message="布局与主题 token 回归场景"
        description="切换导航主题并悬停 Dashboard，检查深色菜单、弹层背景和 Card token。缩窄窗口可验证移动抽屉。"
      />
      <Segmented
        value={navTheme}
        options={[
          { label: '浅色导航', value: 'light' },
          { label: '真实深色', value: 'realDark' },
        ]}
        onChange={(value) => setNavTheme(value as 'light' | 'realDark')}
      />
      <ConfigProvider theme={{ components: { Card: { headerFontSize: 22 } } }}>
        <ProConfigProvider
          token={{
            colorPrimary: '#722ed1',
            components: { Card: { headerBg: '#f9f0ff' } },
            layout: {
              header: { colorBgMenuElevated: '#141414' },
            },
          }}
        >
          <ProCard title="ProConfigProvider Card token">
            <CheckCard title="CheckCard 继承主题" description="#8929 #9125" />
          </ProCard>
          <div style={{ height: 480, marginBlockStart: 16 }}>
            <ProLayout
              title="Regression Demo"
              layout="top"
              navTheme={navTheme}
              route={{ routes }}
              location={{ pathname: '/dashboard/analysis' }}
              menu={{ request: async () => routes }}
            >
              <PageContainer title="首屏布局稳定">
                移动端抽屉、菜单分组、SSR 与首屏 padding 由对应自动化测试覆盖。
              </PageContainer>
            </ProLayout>
          </div>
        </ProConfigProvider>
      </ConfigProvider>
    </Space>
  );
};

#Use with umi plugins

ProLayout works best with umi. umi automatically injects the routes from config.ts into the configured layout for us, so we don't have to write the menus by hand.

ProLayout extends umi's router configuration, adding name, icon, locale, hideInMenu, hideChildrenInMenu and other configurations, so that it is easier to generate menus in one place. The data format is as follows.

export interface MenuDataItem {
  /** @name submenu */
  routes?: MenuDataItem[];
  /** @name Hide child nodes in the menu */
  hideChildrenInMenu?: boolean;
  /** @name hideSelf and children in menu */
  hideInMenu?: boolean;
  /** @name Icon of the menu */
  icon?: React.ReactNode;
  /** @name Internationalization key for custom menus */
  locale?: string | false;
  /** @name The name of the menu */
  name?: string;
  /** @name is used to calibrate the selected value, default is path */
  key?: string;
  /** @name disable menu option */
  disabled?: boolean;
  /** @name path */
  path?: string;
  /**
   * When this node is selected, the node of parentKeys is also selected
   *
   * @name custom parent node
   */
  parentKeys?: string[];
  /** @name hides itself and elevates child nodes to its level */
  flatMenu?: boolean;
  /** @name specify the external link opening form, same as a tag */
  target?: string;

  [key: string]: any;
}

ProLayout will automatically select the menu based on location.pathname and automatically generate the corresponding breadcrumbs. If you don't want to use it, you can configure selectedKeys and openKeys yourself for controlled configuration.

#API

#ProLayout

All methods suffixed with Render can be made not to render by passing false.

#menu

menu supports some commonly used menu configurations to help us better manage menus

#SettingDrawer

Built-in color list

const colorList = [
  { key: 'daybreak', color: '#1890ff' },
  { key: 'dust', color: '#F5222D' },
  { key: 'volcano', color: '#FA541C' },
  { key: 'sunset', color: '#FAAD14' },
  { key: 'cyan', color: '#13C2C2' },
  { key: 'green', color: '#52C41A' },
  { key: 'geekblue', color: '#2F54EB' },
  { key: 'purple', color: '#722ED1' },
];

#PageLoading

A simple loading page

#getMenuData

Generate menuData and breadcrumb based on router information.

import { getMenuData } from '@ant-design/pro-components';

const { breadcrumb, menuData } = getMenuData(
  routes,
  menu,
  formatMessage,
  menuDataRender,
);

#getPageTitle

getPageTitle encapsulates the logic of the title generated on the menuData.

import { getPageTitle } from '@ant-design/pro-components';

const title = getPageTitle({
  pathname,
  breadcrumb,
  menu,
  title,
  formatMessage,
});

#Settings

// You can get this type by importing { Settings } from '@ant-design/pro-layout/defaultSettings'
// to get this type
export interface Settings {
  /** theme of nav */
  navTheme: 'light' | 'realDark';
  /** Primary color of ant design */
  colorPrimary: string;
  /** Nav menu position: `side` or `top` or `mix` */
  layout: 'side' | 'top' | 'mix';
  /** Layout of content: `Fluid` or `Fixed`, only works when layout is top */
  contentWidth: 'Fluid' | 'Fixed';
  /** Sticky header */
  fixedHeader: boolean;
  /** Sticky siderbar */
  fixSiderbar: boolean;
  /** menu configuration */
  menu?: {
    locale?: boolean;
    hideMenuWhenCollapsed?: boolean;
    collapsedShowTitle?: boolean;
    collapsedShowGroupTitle?: boolean;
    defaultOpenAll?: boolean;
    ignoreFlatMenu?: boolean;
    loading?: boolean;
    onLoadingChange?: (loading?: boolean) => void;
    params?: Record<string, any>;
    request?: (
      params: Record<string, any>,
      defaultMenuData: MenuDataItem[],
    ) => Promise<MenuDataItem[]>;
    type?: 'sub' | 'group';
    autoClose?: false;
    collapsedWidth?: number;
  };
  /** Layout title, also displayed in the browser tab */
  title?: string | false;
  /** Your custom iconfont Symbol script Url */
  iconfontUrl?: string;
  /** Global color filter */
  colorWeak?: boolean;
  /** Split menus, only works in mix mode */
  splitMenus?: boolean;
  /** Hide Sider when menu is empty */
  suppressSiderWhenMenuEmpty?: boolean;
  /** Sider menu type */
  siderMenuType?: 'sub' | 'group';
}

#MenuDataItem

// You can get this type by importing { MenuDataItem } from '@ant-design/pro-components'
// to get this type
export interface MenuDataItem {
  authority?: string[] | string;
  children?: MenuDataItem[];
  hideChildrenInMenu?: boolean;
  hideInMenu?: boolean;
  icon?: string;
  locale?: string;
  name?: string;
  path: string;

  [key: string]: any;
}

#Route

// You can get this type by importing { RouterTypes } from '@ant-design/pro-layout/lib/typings';
// to get this type
export interface Route {
  path: string;
  children: Array<{
    exact?: boolean;
    emoji: string;
    name: string;
    path: string;
    // Optional secondary menu
    children?: Route['children'];
  }>;
}

#Footer

The default ProLayout does not provide a footer, but does provide a DefaultFooter component that supports the configuration of some hyperlinks and some copyright information.

import { GithubOutlined } from '@ant-design/icons';
import { DefaultFooter } from '@ant-design/pro-components';

<DefaultFooter
  copyright="@2019 by Ant Financial Experience Technology Department"
  links={[
    {
      key: 'Ant Design Pro',
      title: 'Ant Design Pro',
      href: 'https://pro.ant.design',
      blankTarget: true,
    },
    {
      key: 'github',
      title: <GithubOutlined />,
      href: 'https://github.com/ant-design/ant-design-pro',
      blankTarget: true,
    },
    {
      key: 'Ant Design',
      title: 'Ant Design',
      href: 'https://ant.design',
      blankTarget: true,
    },
  ]}
/>;

#GridContent

GridContent is a simple syntactic sugar that encapsulates ProLayout's contentWidth configuration. contentWidth, if set to Fixed fixed-width mode, is only 1200px at its widest.

Usage.

<GridContent>{children}</GridContent>

GridContent encapsulates the equal-width and flow logic. You can see the preview effect in preview.

#RouteContext

RouteContext can provide built-in data for Layout. For example, isMobile and collapsed, which you can consume to customize some of the behavior.

RouteContext also allows you to perform operations based on layout data, and PageContainer and FooterToolbar rely on RouteContext data to function.

import { RouteContext, RouteContextType } from '@ant-design/pro-components';

const Page = () => (
  <RouteContext.Consumer>
    {(value: RouteContextType) => {
      const { isMobile, hasHeader, hasSiderMenu, collapsed } = value;
      // User's title
      return value.title;
    }}
  </RouteContext.Consumer>
);

#Token

Tokens are a basic element of a design system that allows you to quickly modify the underlying style of a component library using Tokens. These colors can be configured in Layout through the token property.

#Layout token

#Sider Token

Sider Token is the color value of the side menu, which is different from the top menu.

#Header Token

#pageContainer Token

#FAQ

#Customizing Layout

ProLayout provides some api to remove areas that are not needed by the user. Some configurations are also provided in SettingDrawer to set them.

• headerRender can customize the top bar
• footerRender can customize the footer
• menuRender can customize the menu area
• menuHeaderRender Customizable menu header area
• menuExtraRender can add an extra content to the menu, between the menu header and the menu

All xxxRender in layout can be passed in false to turn off rendering.

#Use with Umi

ProLayout works best with Umi, Umi will automatically inject the routes from config.ts into the configured layout, saving us the trouble of writing menus by hand.

ProLayout extends Umi's router configuration, adding name, icon, locale, hideInMenu, hideChildrenInMenu and other configurations, so that it is easier to generate menus in one place. The data format is as follows:

export interface MenuDataItem {
  /** @name submenu */
  children?: MenuDataItem[];
  /** @name Hide child nodes in the menu */
  hideChildrenInMenu?: boolean;
  /** @name hideSelf and children in menu */
  hideInMenu?: boolean;
  /** @name Hide in breadcrumb */
  hideInBreadcrumb?: boolean;
  /** @name Icon of the menu */
  icon?: React.ReactNode;
  /** @name Internationalization key for custom menus */
  locale?: string | false;
  /** @name The name of the menu */
  name?: string;
  /** @name is used to calibrate the selected value, default is path */
  key?: string;
  /** @name disable menu option */
  disabled?: boolean;
  /** @name path, can be set to a web link */
  path?: string;
  /**
   * @deprecated When this node is selected, the node of parentKeys is also selected
   * @name custom parent node
   */
  parentKeys?: string[];
  /** @name hides itself and elevates child nodes to its level */
  flatMenu?: boolean;
  /** @name specify the external link opening form, same as a tag */
  target?: string;

  [key: string]: any;
}

ProLayout will automatically select the menu based on location.pathname and automatically generate the corresponding breadcrumbs. If you don't want to use it, you can configure selectedKeys and openKeys yourself for controlled configuration.

#Collapse to expand

Sometimes we find that collapsed and onCollapse do not work by default. This is because ProLayout has a built-in breakpoint mechanism to trigger collapse, we can set breakpoint={false} to turn off this mechanism.

To toggle the sidebar from any component, lift collapsed into shared state and pass collapsed={collapsed} plus onCollapse={setCollapsed} to ProLayout. A reusable toggle action is () => setCollapsed(value => !value).

#Customize the width of the menu

siderWidth can customize the width of the menu, you can set it shorter or longer FooterToolbar and other components will automatically support, but may need to do some style processing, otherwise the menu display may have some small problems.

The width of the menu is not customizable because it involves animation and huge amount of css changes, which is very difficult to customize.

#Auto-cut menu

Auto-cut menu is an exclusive ability of mix mode to place the first level of the menu into the top bar. We can set splitMenus=true to turn it on, and for a good experience it's best to set a redirect for each level of the menu, which will prevent switching to a white screen page.

#Customizing menus

ProLayout will automatically generate the menu and auto-select it according to pathname. Combined with PageContainer, this allows for automatic breadcrumb and page title projection. If used with the Umi configuration, you only need to hand the Page props to ProLayout to automatically generate the configuration of the menu based on the configuration of routers in config.

In order to provide more functionality, we extended the routers configuration by adding several configurations for customization, with the following data structure definition:

// You can get this type by importing { MenuDataItem } from '@ant-design/pro-components'
// to get this type
export interface MenuDataItem {
  children?: MenuDataItem[];
  hideChildrenInMenu?: boolean;
  hideInMenu?: boolean;
  icon?: string;
  locale?: string;
  name?: string;
  path: string;
  [key: string]: any;
}

• name is used to configure the name in the menu, and will be modified to the browser tab title
• icon represents the body of the menu, only antd's icon, iconfont needs to be defined by yourself
• locale can set the internationalization of the menu name
• hideInMenu will be configured to hide this route in the menu, name will have the same effect if not filled
• hideChildrenInMenu will hide the children of this route in the menu

ProLayout actually reads the route and location from the props, which are injected by default by Umi.

#Getting from the server

Sometimes we want the server to manage our routes, so we want the menus to be distributed by the server. We provide menuDataRender to modify the data, but note that menuDataRender will trigger re-rendering and will also support internationalization and permission configuration, so if you don't need internationalization, we recommend using postMenuData for a significant performance boost.

The server needs to return the same data as MenuDataItem, menuDataRender needs to return an array, if you want to have better performance you can try using the route property in props, here is a demo.