Page Layout Guidelines

[cchaos]

As Elastic products convert existing pages to the new EuiPageTemplate component, here are some common guidelines to follow.

These can also be found in the (private) Figma file: Page layout guidelines

[cchaos]

Converting from the legacy (panelled) layout to the new EuiPageTemplate

Be sure that the page component can fully stretch in height. If it is not, it is usually due to insufficient flex wrappers.
If you are working in Kibana, you can use the new APP_WRAPPER_CLASS to apply to any elements that wrap the EuiPageTemplate.

Don't: Use blank element wrappers before the page template
Do: Remove unnecessary divs or apply the APP_WRAPPER_CLASS

Convert to using the built-in pageHeader prop

Don’t nest EuiPageHeader inside of the template. Instead, pass the contents as pageHeader configuration props.

Don't: Use old EuiPage components or panels for wrapping entire page layouts
Do: Use EuiPageTemplate with incorporated EuiPageHeader via pageHeader

[cchaos]

Empty pages

When the whole page is empty

Use EuiPageTemplate prop template="centeredBody" and the EuiEmptyPrompt component/pattern to replace the whole page.

Don't: Just replace page content with a simple sentence.
Do: Utilize the empty state pattern.

Don't: Use an ambiguous empty state without any actions.
Do: Utilize the empty state pattern with a specific call to action.

Empty state due to insufficient permissions

Provide language that specifically points to permissions as the reason for the empty state. If possible, link to an admin contact.

Don't: Use an ambiguous empty state without any actions because of permissions.
Do: Provide more explanation within an empty state.

Empty page content that still needs the page header

Use the EuiEmptyPrompt but inside of the page body with a subdued panel wrapper. Remove any UI that can’t be used due to the emptiness.

Don't: Show an empty table with filters that won’t filter anything.
Do: Hide unusable elements and utilize the empty state with one or more specific calls to action.

[cchaos]

Centering content

Whether or not the page has side navigation, any empty/loading/error states that take up the whole page should be vertically and horizontally centered.

Don't: Forget to use the centeredContent template for empty states.
Do: Use the centeredContent template for empty states even when using tabs.

---

Don't: Use centeredBody with pageSideBar
Do: Use centeredContent instead

---

Don't: Don’t duplicate content from page header to empty state contents.
Do: Utilize one of the centered templates and move all page header contents to the empty prompt.

---

Do: Use centeredContent when using tabs that have separate empty states. Whether the page has a side bar or not.

[cchaos]

Error and loading states

Remove page header on full page errors

It is usually unnecessary to display the page header if the whole page has an error. This just creates repetitive content.

Don't: Display the page header if the page can’t be accessed or has an error.
Do: Reduce repetitive content and just display the error message.

When loading content

If, after loading, the entire page renders as an empty or error state, the loading state should also be an entire page.

Don't: Show possibly temporary content like the page header when loading.

Do: Use the centeredContent loading state followed by the centeredContent error/empty state (or loaded content).

---

Callouts versus empty prompts

Only use the EuiEmptyPrompt when the whole page is empty or an error and never use multiple empty prompts on the same page.

Don't: Use multiple large empty prompts when there is still page content.
Do: Use the EuiCallOut components

---

Tabbed content

Treat the page contents under tabs as “full page” content, using empty prompts for empty/loading/error states if it is the only content that is rendered as the tab content. However, the context of the state should dictate whether an empty prompt or simple callout is appropriate.

Do: If the error blocks all interactions of the tabbed content, a centered empty prompt may be warranted.
Do: If the error is not detrimental or blocking lots of user interaction, a simple callout may suffice. Though this example could also be an empty prompt.

[ryankeairns]

Closing as the conversion has been completed. These still stand as useful guidelines that could be captured in our patterns work. cc:/ @mdefazio @andreadelrio

[cee-chen]

These guidelines should exist in the docs: https://elastic.github.io/eui/#/templates/page-template/guidelines