Page template guidelines
Converting from legacy layouts
Try to use as much of the namespaced (e.g.
<EuiPageTemplate.Header />) as much as possible. This will ensure that top level props are propogated through and alignment is kept through the stacking order. You can use the non-namespaced versions (e.g. <EuiPageSection>) if you deliberately don't want the props to inherit.
Do: Use EuiPageTemplate with incorporated EuiPageTemplate.Header and EuiPageTemplate.Section
Don't: Using plain EuiPage components for wrapping entire page layouts is very manual and no longer matches the template.
When to center 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 using alignment="center" on the individual page section.
Most empty states can utilize the <EuiPageTemplate.EmptyState> which will automatically center the content for you.
Do: Use fully centered alignment for empty states even when using tabs.
Don't: Horizontally centered only content will mismatch the basic template.
Do: Utilize the empty prompt component for fully empty pages and hide the page header.
Don't: Duplicate content between page header and empty state contents isn't helpful.
Empty pages
When the whole page is empty
Use the EuiPageTemplate.EmptyPrompt component to replace the whole page.
Do: Utilize the empty state component which automatically adds panelling and centering.
Don't: Just replacing page content with a simple sentence creates incorrect hierarchy.
Do: Utilize the empty state component with a specific call to action.
Don't: Ambiguous empty state messages without any actions are not helpful.
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.
Do: Provide more explanation within the empty state.
Don't: Ambiguous empty states without any actions can feel like an error.
Empty page content that still needs the page header
If necessary, the EuiPageTemplate.EmptyPrompt can be still be used alongside EuiPageTemplate.Header. Remove any UI that can't be used due to the emptiness.
Do: Hide unusable elements and utilize the empty state with one or more specific calls to action.
Don't: Empty tables with filters that won't find any results and duplicate actions are not necessary.
Do: Use only the empty prompt with explanations and a call to action.
Don't: Page headers are not as necessary when the same labelling is used throughout other parts of the page.
Error and loading states
When loading the content
If, after loading, the entire page renders as an empty or error state, the loading state should also be an entire page.
Do: Use the empty prompt as a loading state followed by an empty prompt styled as a error/empty state (or loaded content).
Don't: Temporarily showing content like the page headers when loading then removing those elements on error is jarring.
Callouts versus empty prompts
Typically there should only be one EuiPageTemplate.EmptyPrompt when the whole page is empty or an error. They should never be used to stack multiple errors on the same page.
Do: Use the EuiCallOut components for stacking error messages alongside content.
Don't: Multiple large empty prompts pushes the main content out of view and, without actions, harms UX.
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.