Flyout

A Flyout is used to show and hide additional information and content that is related to the main page without navigating or routing to a new page.

Usage

When to use

• When displaying additional information, context, or details that extend or enhance an object or element on the main page.
• To present functions that are secondary to the main page or user flow.
• To preview content without navigating or routing to a new page.

When not to use

• When requesting information or feedback from the user through a form. Instead, use a Modal or consider moving the content to its own page.
• When displaying overly complex information, consider moving the content to its own page.

Flyout vs Modal

While similar in functionality and interaction, the Flyout and Modal are meant to be used in different scenarios and to express different types of content. There is a fair amount of overlap in their usage but they differ in complexity, status and messaging, speed and regularity, and experience hierarchy.

Complexity

A Flyout is useful for more complex content, given the space it occupies in the viewport, while Modals are useful for less complex content that can be interacted with quickly.

Status and messaging

Flyouts are useful when displaying detailed content that relates to the page, while Modals are useful for messaging status, e.g., confirming a destructive action or warning about the effects of a change.

Speed and regularity

Modals are better suited for quick interactions that occur infrequently, while Flyouts, due to their support for more complex content, can occupy more of the users’ time and be recalled more frequently.

Experience hierarchy

While each of these components is triggered by a user action, where they exist in the flow is fundamentally different:

• A Modal blocks the user from progressing further in the main flow (Fig 1.0), forcing them to take action or make a decision.
• A Flyout extends or "branches" off from the main flow to add detail and highlight secondary features and functions (Fig 1.1).
• Rather than blocking the user from continuing in the main flow, a Flyout enhances and adds detail to the flow to aid in the completion of a function.

Fig. 1.0: Hierarchy representation of a Modal blocking the user progression through a flow.

Fig. 1.1: Hierarchy representation of the Flyout relative to the user flow.

Usage examples

Preview content

Previewing read-only content is an ideal use case for a Flyout as it keeps the user in the context of the current flow while detailing additional secondary information.

Code snippets and examples

While code snippets and terminal scripts are usually detailed, they are well suited content within a Flyout due to their contextual relevancy to the content on the page, while maybe not being complex enough to exist on their own page.

Forms

Don't use a form in a Flyout, whether the function is creating an object, or updating an existing one. This type of content is often complex and more appropriate on its own page, or in the case of a simple form, within a Modal.

Size

The available sizes are medium (default) and large.

Best practices

• Use a Flyout size that best accounts for the complexity and detail of the content.
• The medium size accounts for the majority of scenarios and is the default recommended size.

Flyout header

The Flyout header features several properties to better communicate the purpose and content within the component.

Title icon

With title icon

Without title icon

Usage

An icon paired with the title can help reinforce the purpose and function of the Flyout while also drawing the eye to the header and title area.

The purpose and function of the Flyout should not rely solely on an icon, instead the title should be explicit and pragmatic while the icon provides visual support.

Tagline

With tagline

With tagline and icon

A tagline helps the user maintain the context of the main page the Flyout was triggered from. Since a Flyout disables and obscures the main page content, adding a tagline can help the user understand the relationship between the Flyout and the main page.

The tagline should directly reference the page, feature title, or object to reinforce the purpose of the Flyout.

Description

A description provides additional information about the Flyout.

With description

With description and icon

Flyout body

The body of the Flyout supports any generic content, local components, or Helios components via an instance swap property (genericInstance) in Figma. In code, yield is supported.

Flyout footer

The Flyout footer is a persistent content area at the bottom of the Flyout, and supports additional descriptive content, links, actions, and any other generic content or Helios components.

The Ember and Figma components account for the footer in slightly different ways, though both can achieve the same results:

• The Ember component is a generic container that yields elements passed to it.
• The Figma component consists of a variant for the number of actions, as well as support for generic content via an instance swap property.

With one action

With two actions

For more guidance and details around organizing buttons and actions, refer to the Button organization pattern documentation.

Actions

A Flyout supports actions within the footer allowing for basic functions to be performed. This usage should be limited to performing secondary functions that are related to the main page to help the user maintain context in the primary flow. Some examples of this are:

• Batch updating and creating relationships between one or more objects
• Linking to external resources using a link that appears as a button

Dismissal

The primary dismissal method for the Flyout is the dismiss action in the header. The Flyout does not support action buttons to “confirm” or “cancel” the Flyout as the component is not intended to perform functions.

Multiple dismissal options are available that can be customized in production with a callback (on onClose, or onOpen) function:

• Dismiss button in the header
• Clicking with a mouse outside of the Flyout on the main page
• Hitting the escape (ESC) key on a keyboard

Positioning and responsive sizing

A Flyout should slide out from the right side of the viewport on top of the main page content and occupy 100% of the viewport height.

• This is true regardless of whether there is a sidebar or navigational element that persists on the page.
• A Flyout should overlay all content and block/disable interaction on the main page.

On smaller viewports, the Flyout should occupy 100% of the viewport width minus half the size of the minimized SideNav width from the viewport edge.

• If the body content of the Flyout exceeds the maximum height of the viewport, a scroll will be introduced.
• The Flyout header is not included in the scrolling section, only the body content. The header should always be visible to help the user understand the Flyout content and how it relates to the main page.
• The Flyout should not be resized manually, rather select the size that best accommodates the content.

Browser support

The Flyout component leverages the <dialog> element which is currently supported by all major browser vendors.

Page scroll

When a Flyout is open, the rest of the page becomes inert. The page scrolling is also disabled by applying overflow: hidden to the <body> element, to make it clear to the user that the underlying elements are not interactive and to avoid confusion. Depending on users’ scroll bar settings, opening a Flyout may cause slight layout shifts on the horizontal axis.

Positioning

As an overlaying component, the Hds::Flyout is rendered on the top layer, meaning it is always placed on top of all other elements in the page.

Focus trap

This component uses ember-focus-trap to prevent the focus from going outside the Flyout and to deactivate the Flyout when clicking outside. This Ember modifier requires at least one interactive element to be present within the Flyout, which is by default achieved by the dismiss button in the header.

Focus and focus trap

This component uses ember-focus-trap to prevent the focus from going outside the Flyout and to dismiss the Flyout when clicking outside the Flyout. This Ember modifier requires at least one interactive element to be present within the Modal, which is by default achieved by the dismiss button in the header.

When a Modal is opened with the keyboard, the focus is automatically set to the first focusable element inside the Modal, which is the “Dismiss” button. The action of this button has no effect on the system, so focusing on it helps prevent users from accidentally confirming the Modal.

When the Flyout has been closed, the browser automatically returns the focus to the element that initiated the opening. If that element doesn't exist anymore in the DOM (e.g., if the Flyout is opened using an Interaction item in a Dropdown) the focus is returned to the <body> element. To avoid this side-effect (that comes with accessibility implications), it's possible to use the @returnFocusTo argument, where the consumer can provide the DOM id attribute of the element where the focus should be returned once the Flyout is closed.

How to use this component

<Hds::Button
  @text="Open Flyout"
  @color="secondary"
  {{on "click" (fn this.activateFlyout "basicFlyoutActive")}}
/>

{{#if this.basicFlyoutActive}}
  <Hds::Flyout id="basic-flyout"
    @onClose={{fn this.deactivateFlyout "basicFlyoutActive"}} as |M|>
    <M.Header @tagline="Main page context" @icon="info">
      Additional information
    </M.Header>
    <M.Description>
      Lorem ipsum dolor sit amet consectetur.
      Ut ultrices id venenatis in felis auctor ante.
    </M.Description>
    <M.Body>
      <p class="hds-typography-body-300 hds-foreground-primary">
        Aliquam ac enim iaculis, faucibus enim id, dapibus quam.
        Nunc nibh mi, vehicula sed enim eget, lacinia venenatis tortor.
        Quisque vitae accumsan est, eu vehicula arcu.
      </p>
    </M.Body>
  </Hds::Flyout>
{{/if}}

Component API

Flyout

Contextual components

[F].Header

The DialogPrimitive::Header component, yielded as contextual component.

[F].Description

The DialogPrimitive::Description component, yielded as contextual component.

[F].Body

The DialogPrimitive::Body component, yielded as contextual component.

[F].Footer

The DialogPrimitive::Footer component, yielded as contextual component.

Anatomy

Conformance

The Flyout component is conformant when used as directed.

Focus

When a Flyout is triggered, focus is trapped within the component. The dismiss button should receive focus as the first interactive element in the DOM (document object model).

Applicable WCAG Success Criteria

This section is for reference only, some descriptions have been truncated for brevity. This component intends to conform to the following WCAG Success Criteria:

Support

If any accessibility issues have been found within this component, let us know by submitting an issue.

4.15.0

Updated

Aligned private class properties to follow a standardized notation

4.13.0

Updated

Added returnFocusTo argument to control where the browser focus is returned once the flyout is closed

Removed isDismissDisabled from signature (not an actual argument)

4.12.0

Updated

Fixed issue with box-sizing inheritance due to a all: unset CSS rule applied to the DialogPrimitive subcomponent

4.10.0

Updated

Flyout.Header

Changed the HTML element wrapping the tagline and title from a <div> to a <h1>. If you have a heading HTML tag inside the header yield block, either remove it or change it to a <span>.

4.7.0

Deprecated

In this version, the Flyout sub-components have been deprecated and replaced with the equivalent DialogPrimitive sub-components (shared also with the Modal component). The deprecated Flyout sub-components will be removed in the next major release.

To do the migration, if you use the <Hds::Flyout::***> invocation:

If instead you use the (component hds/flyout/***):

In the refactoring, we have been able to maintain existing CSS class names to avoid breaking current tests and CSS overrides in consumers' codebases.