Page template
EuiPageTemplate is a namespaced component for creating the different types of page layout patterns described in these docs. It is somewhat opinionated, but still has the ability to customize most of the inner components directly on their instance.
Simple page with header and sections
All templates should start with a wrapping
EuiPageTemplate to control some shared settings like paddingSize, bottomBorder, restrictWidth, and panelled. Then each direct child will be evaluated for if it is one of the other namespaced components. If so, it will place it in the appropriate spot and apply the appropriate props based on the full configuration of child elements. These namespaced components include:
- EuiPageTemplate.Sidebar extends EuiPageSidebar
- EuiPageTemplate.Header extends EuiPageHeader
- EuiPageTemplate.Section extends EuiPageSection
- EuiPageTemplate.BottomBar extends EuiBottomBar
- EuiPageTemplate.EmptyPrompt extends EuiEmptyPrompt
With the exception of .Sidebar and .BottomBar, the stacking order of the page contents is determined by the order they are passed in. You can also override the outer props by simply applying them directly to the child element.
If you have a fixed position headers, the template will automatically account for the padding offset based on the total number of page headers. If you do not want the template to calculate this, you can pass 0 in as the manual offset.
Providing a sidebar
If your application requires the use of side navigation or other sidebar content, you can pass and EuiPageTemplate.Sidebar component containing your sidebar content. The template will automatically adjust the layout when this content is provided.
This component will set its content to stick to the top of the browser window and scroll independently of the rest of the layout. If you have any fixed EuiHeaders, these will be accounted for as well. You can turn this behavior off with sticky={false}.
Typically when a sidebar is included and restrictedWidth is defined, we recommend keeping the borderBottom={true} though you can also expand particular sections with borderBottom="extended".
Sidebars must be direct children declared in the same component.
In order for the template configurations to properly account for the existence of a sidebar, it needs to clone the element which can only be performed on direct children.
Showing a bottom bar
Adding an EuiBottomBar can be tricky to use and account for any sidebars. EuiPageTemplate handles this nicely by supplying a EuiPageTemplate.BottomBar component for passing the contents of your bottom bar that extends EuiBottomBar.
It uses the sticky position so that it sticks to the bottom of and remains within the bounds of page body. This way it will never overlap the sidebar, no matter the screen size. It also means not needing to accommodate for the height of the bar in the body element.
It will also keep its content constrained to the restrictedWidth value so the contents are always horizontally aligned.
For proper alignment in case of short content, at least one EuiPageTemplate.Section must have grow={true}.
Empty pages or content
When the content is in an empty/pre-setup state, we recommend then using an EuiEmptyPrompt to direct users on next steps. Using EuiPageTemplate.EmptyPrompt will automatically center the prompt vertically and horizontally.
The prompt's panel color depends on the other configurations but can be manually passed in via the color prop.
Props
EuiPageTemplate
Prop | Description and type | Default value |
|---|---|---|
Prop grow# | Description and type Adds boolean | Default value true |
Prop direction# | Description and type Changes the "column" | "row" | Default value |
Prop responsive# | Description and type When direction is string[] | Default value ['xs', 's'] |
Prop className# | Description and type Type: string | Default value |
Prop aria-label# | Description and type Defines a string value that labels the current element. string | Default value |
Prop data-test-subj# | Description and type Type: string | Default value |
Prop css# | Description and type Type: Interpolation<Theme> | Default value |
Prop paddingSize# | Description and type Adjust the overall padding. "xs" | "s" | "m" | "l" | "xl" | "none" | Default value l |
Prop ref# | Description and type Allows getting a ref to the component instance. LegacyRef<HTMLElement> | Default value |
Prop panelled# | Description and type Adds a white background and shadow to define the area. boolean | Default value |
Prop restrictWidth# | Description and type Sets the max-width of the page, string | number | boolean | Default value true |
Prop bottomBorder# | Description and type Adds a bottom border to separate it from the content after; boolean | "extended" | Default value |
Prop contentBorder# | Description and type Applies a top or left border to the inner contents boolean | Default value |
Prop minHeight# | Description and type Minimum height in which to enforce scrolling MinHeight<string | number> | Default value 460px |
Prop offset# | Description and type To account for any fixed elements like headers, number | Default value |
Prop mainProps# | Description and type Passes through some common HTML attributes to the CommonProps & HTMLAttributes<HTMLElement> | Default value |
Prop component# | Description and type Sets which HTML element to render for the ComponentTypes | Default value main |