Restore Flyout System feature in EUI #9202

tsullivan · 2025-11-10T17:39:45Z

New Managed Flyout System

Re-open of #9068

This represents a significant evolution in the flyout system: a hook-based manager system with automatic context detection and support for complex flyout workflows.

Summary of API changes

Change	Component	API	Brief description and documentation
New optional prop	EuiFlyout	`session?` (`'start' \| 'never' \| 'inherit'`, optional - defaults to `inherit`)	Enable flyout session management. Read more Documentation: https://eui.elastic.co/pr_9202/docs/components/containers/flyout/#EuiFlyout-prop-session
New optional prop	EuiFlyout	`onActive?` (`() => void`, optional)	Callback fired when the flyout becomes active/visible. Documentation: https://eui.elastic.co/pr_9202/docs/components/containers/flyout/#EuiFlyout-prop-onActive
New optional prop	EuiFlyout	`resizable?` (boolean, optional - defaults to `false`)	A new way to create resizable flyouts available directly in EuiFlyout - no EuiFlyoutResizable necessary. The `resizable` prop is dynamic which allows toggling between resizable state without whole-component rerenders This makes the old EuiFlyoutResizable component obsolete (but it still works exactly like before). We may officially deprecate it in near future, but that's not the goal of this project. Read more Documentation: https://eui.elastic.co/pr_9202/docs/components/containers/flyout/#resizable-flyout
New optional prop	EuiFlyout	`onResize?`	Documentation: https://eui.elastic.co/pr_9202/docs/components/containers/flyout/#EuiFlyout-prop-onResize
New optional prop	EuiFlyout	`minWidth?` (number, optional)	Brings feature parity with EuiFlyoutResizable. Use with `resizabe={true}` to set a minimum width of the flyout. Documentation: https://eui.elastic.co/pr_9202/docs/components/containers/flyout/#resizable-flyout
New optional prop	EuiFlyout	`flyoutMenuProps?` (EuiFlyoutMenuProps, optional)	Allows configuring certain aspects of the flyout menu like the title or custom action buttons. Read more Documentation: https://eui.elastic.co/pr_9202/docs/components/containers/flyout/#flyout-menu
New optional prop	EuiFlyout	`hasChildBackground?`	Documentation: https://eui.elastic.co/pr_9202/docs/components/containers/flyout/#EuiFlyout-prop-hasChildBackground
`ref` prop update	EuiFlyout	`ref?` (`React.Ref`, optional)	Breaking change Legacy string refs are no longer supported with EuiFlyout. Use modern React refs like `useRef` instead. Read more
Removed old flyout session system	EuiFlyoutSessionProvider useEuiFlyoutSession EuiFlyoutSessionApi EuiFlyoutSessionConfig EuiFlyoutSessionRenderContext	-	The initial, experimental flyout system implementation has been removed. Read more
Removed	EuiFlyoutChild

ADDED - New Public-Facing Features

1. New Manager System

A comprehensive new "manager" system for centralized management of flyout sessions (src/components/flyout/manager/):

Core Component:

EuiFlyout: Same flyout component that developers are accustomed to

Session Management Props:

session prop on EuiFlyout with three modes:
- 'start' - Creates a new flyout session (for main flyouts)
- 'inherit' - (default) Inherits existing session if active
- 'never' - Opts out of session management

Required EuiFlyoutMenu:
Managed flyouts require an EuiFlyoutMenu at the top, which is automatically rendered when you provide the necessary props.

flyoutMenuProps.title - (Required, or provide aria-label) Prop that provides the title for the automatically rendered EuiFlyoutMenu. Additional properties in flyoutMenuProps allow further customization of the menu (back button, history items, custom actions, etc.).

Synchronizing local state with the visible flyout session:
Since flyout sessions can be programmatically activated, i.e the history navigation system can reactivate them, you may want to have a local state that is kept in sync with the active session. These callbacks can be used to update your local state variables:

onActive callback - Fires when flyout becomes active/visible (new prop)
onClose callback - Fires when flyout is closed (not a new prop)

The new manager system uses use-sync-external-store and a singleton store pattern for cross-React-root state sharing.

2. New Flyout Menu Component

EuiFlyoutMenu and EuiFlyoutMenuProps: A new component for rendering a top menu bar in EuiFlyout.
The component uses internal context to support a "Back" button and a "History popover" control, when used within a managed flyout context.

3. `resizable` prop.

EuiFlyoutResizable was a complex wrapper that managed all resizing and state logic internally. The logic has been moved to an internal hook, which is now integrated directly into the main flyout component.

EuiFlyout now supports a resizable boolean prop
EuiFlyoutResizable is still supported, but is just a wrapper for EuiFlyout with resizable set to true.

REMOVED - Earlier iteration of the Flyout System Feature

An earlier pre-release iteration of the Flyout System was in main but is now being removed.

1. Old Session System

The entire API of the earlier version is being removed:

~~EuiFlyoutSessionProvider~~
~~useEuiFlyoutSession()~~
~~EuiFlyoutSessionApi~~
~~EuiFlyoutSessionConfig~~
~~EuiFlyoutSessionOpenChildOptions~~
~~EuiFlyoutSessionOpenMainOptions~~
~~EuiFlyoutSessionOpenGroupOptions~~
~~EuiFlyoutSessionProviderComponentProps~~
~~EuiFlyoutSessionRenderContext~~

2. Old Child Flyout Implementation

~~Standalone EuiFlyoutChild component~~ (replaced with managed version)

The key difference from the old session system is that it used render props; the new manager system uses a centralized state store with hooks. The old system required explicit provider wrapping; the new system automatically detects when to use managed behavior.

Number of component usages in Kibana that will need to be updated: 0

Screenshots #

Impact to users #

BREAKING CHANGE - String Refs No Longer Supported

EuiFlyout is a forwardRef component that previously had loose typing allowing string refs. It now enforces strict typing that only accepts modern ref patterns. Specifically, this could impact you in two scenarios:

If you were passing a string ref to EuiFlyout, you will need to pass an HTML element ref instead:

const ref = useRef<HTMLDivElement>(null);
<EuiFlyout ref={ref}>
    <div>Hello</div>
</EuiFlyout>

If you were using styled-components to wrap EuiFlyout, your component implicitly becomes a string ref component. You will need to add ref={null} to your component:
```
const StyledEuiFlyout = styled(EuiFlyout)`
padding: 16px;
`;
<StyledEuiFlyout ref={null}>
    <div>Hello</div>
</StyledEuiFlyout>
```

Number of component usages in Kibana that will need to be updated: 1

fleet/sections/agent_policy/list_page/components/create_agent_policy.tsx
- Found using type-checking
- Simple fix

Flyout overlay mask `z-index` value update

Overlay masks are now siblings of flyouts, which required a change to the mask's z-index value. Now, flyout overlay masks use z-index value of levels.flyout - 2 making it more predictable. This stacking order allows child flyouts to have their own z-index layer between the main flyout and the mask.

QA

Remove or strikethrough items that do not apply to your PR.

PR Mergeability / Release readiness checklist

We must ensure this feature has everything it needs to be a publicly available feature in EUI before this branch is merged into main. Please ensure the following are completed before merging this PR:

List explicitly what has been added, removed, or changed in the public facing API.
For each of the above, please ensure documentation has been updated accordingly.
Please provide production(https://eui.elastic.co/) links to all relevant documentation. (which covers, at a minimum, the API changes listed above).
The Impact section must be filled out and call out explicitly how users upgrading to the EUI version containing this feature will be impacted.
- If it is all new code and features, there will be no impact.
- If anything existing in EUI has changed either visually or functionally, it must highlighted.
Figma has been updated to reflect the changes in this PR (or is planned to be updated by the time this feature is published) - please provide links.
- Roadmap issue
- Flyout System design
- See also the "Designer checklist" details below
@JasonStoltz has reviewed the above and approved this PR

General checklist

Browser QA
- Checked in both light and dark modes
- Checked in both MacOS and Windows high contrast modes
  - (emulate forced colors if you do not have access to a Windows machine.)
- Checked in mobile
- Checked in Chrome, Safari, Edge, and Firefox
- Checked for accessibility including keyboard-only and screenreader modes
Docs site QA
- Added documentation
- Props have proper autodocs (using @default if default values are missing) and playground toggles
- Checked Code Sandbox works for any docs examples
Code quality checklist
- Added or updated jest and cypress tests
- [ ] Updated visual regression tests
Release checklist
- A changelog entry exists and is marked appropriately.
- If applicable, added the breaking change issue label (and filled out the breaking change checklist)
Designer checklist
- If applicable, file an issue to update EUI's Figma library with any corresponding UI changes. (This is an internal repo, if you are external to Elastic, ask a maintainer to submit this request)

github-actions · 2025-11-10T20:25:45Z

This PR contains breaking changes. The opener of this pull request is asked to perform the following due diligence steps below, to assist EUI in our next Kibana upgrade:

If this PR contains prop/API changes:
- Search through Kibana for <EuiComponent usages (example search)
- In the PR description or in a PR comment, include a count or list with the number of component usages in Kibana that will need to be updated (if that amount is "none", include that information as well)
If this PR contains CSS changes:
- Search through Kibana for the changed EUI selectors, e.g. .euiComponent (example search)
- In the PR description or in a PR comment, include a count or list with the number of custom CSS overrides in Kibana that will need to be updated (if that amount is "none", include that information as well)
🔍 Tip: When searching through Kibana, consider excluding **/target, **/*.snap, **/*.storyshot files to reduce noise and only look at source code usages
⚠️ For extremely risky changes, the EUI team should potentially consider the following precautions:
- Using a pre-release release candidate to test Kibana CI ahead of time
- Using kibana-a-la-carte for manual QA, and to give other Kibana teams a staging server to quickly test against

Log | Bot Usage

Co-authored-by: Clint Andrew Hall <[email protected]> Co-authored-by: Weronika Olejniczak <[email protected]> Co-authored-by: Tomasz Kajtoch <[email protected]> Co-authored-by: Arturo Castillo Delgado <[email protected]> Co-authored-by: Paulina Shakirova <[email protected]>

…emain for other session (#9207)

…9150) Co-authored-by: Tomasz Kajtoch <[email protected]>

elasticmachine · 2025-11-26T14:16:20Z

💚 Build Succeeded

History

💚 Build #2071 succeeded 50647c5
💚 Build #2070 succeeded 50647c5
💚 Build #2067 succeeded 90731e5
💚 Build #2059 succeeded e9787a9
💚 Build #1924 succeeded cbb5862
💚 Build #1916 succeeded e2b53f0

elasticmachine · 2025-11-26T14:32:51Z

💚 Build Succeeded

Buildkite Build
Commit: 451e83d

History

💚 Build #5318 succeeded 50647c5
💚 Build #5317 succeeded 90731e5
💔 Build #5311 failed e9787a9
💚 Build #5210 succeeded cbb5862
💚 Build #5204 succeeded e2b53f0
💚 Build #5176 succeeded 41f8990

weronikaolejniczak · 2025-11-26T15:34:20Z

packages/eui/changelogs/upcoming/8897.md

@@ -0,0 +1 @@
+Flyout system menu bar: require tile, support custom actions


nit: This was supposed to be "title", right?...

Suggested change

Flyout system menu bar: require tile, support custom actions

- Flyout system menu bar: require title, support custom actions

weronikaolejniczak · 2025-11-26T16:09:14Z

packages/eui/src/components/overlay_mask/overlay_mask.tsx

      }
    });
-  }, [overlayMaskNode]); // eslint-disable-line react-hooks/exhaustive-deps
+    overlayMaskNode.addEventListener('animationend', handleAnimationEnd);


critical doubt: It seems this event listener is not cleaned up anywhere, right? 🤔

weronikaolejniczak · 2025-11-28T12:40:15Z

When testing in Storybook the multi-session story I noticed this issue:

Kapture.2025-11-28.at.13.34.00.mp4

It has to do with our portal and a similar issue has been reported here: #9242.

tsullivan changed the title ~~Restore Flyout System feature in EUI (#9178)~~ Restore Flyout System feature in EUI Nov 10, 2025

tsullivan added the breaking change PRs with breaking changes. (Don't delete - used for automation) label Nov 10, 2025

tsullivan mentioned this pull request Nov 11, 2025

[Grid Layout / Flyout System] When sidebar is visible, child flyouts have wrong positioning elastic/kibana#242610

Open

tsullivan and others added 2 commits November 13, 2025 17:35

set changelogs

e2b53f0

tkajtoch force-pushed the feat/flyout-system branch from 41f8990 to e2b53f0 Compare November 13, 2025 16:35

tsullivan and others added 5 commits November 13, 2025 15:33

[Flyout System] Ensure the push padding for managed flyout does not r…

cbb5862

…emain for other session (#9207)

[Flyout System] Make session logic truly opt-in (#9163)

e9787a9

[EuiFlyoutMenu] add hideTitle prop for “main” flyouts in a session (#…

90731e5

…9150) Co-authored-by: Tomasz Kajtoch <[email protected]>

Merge branch 'main' into feat/flyout-system

da383d2

update test snapshot

50647c5

tsullivan mentioned this pull request Nov 24, 2025

[Flyout System] Child flyout should not overlap parent during animation #9237

Closed

[Flyout system] Dynamic z-index calculation (#9238)

451e83d

tsullivan marked this pull request as ready for review November 26, 2025 15:09

tsullivan requested a review from a team as a code owner November 26, 2025 15:09

weronikaolejniczak reviewed Nov 26, 2025

View reviewed changes

tsullivan mentioned this pull request Nov 26, 2025

Example of Flyout System in Kibana Example elastic/kibana#233806

Draft

tsullivan assigned tsullivan and tkajtoch Nov 26, 2025

MiriamAparicio mentioned this pull request Nov 27, 2025

[ObsUX] Review upcoming EUI flyout changes in Kibana elastic/kibana#244569

Open

iblancof mentioned this pull request Nov 28, 2025

[Discover][APM] Review upcoming EUI flyout changes in Kibana elastic/kibana#244593

Open

kertal mentioned this pull request Nov 28, 2025

[Discover][Tabs] Investigate preserving flyout state when switching tabs elastic/kibana#244639

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Restore Flyout System feature in EUI #9202

Restore Flyout System feature in EUI #9202

Uh oh!

tsullivan commented Nov 10, 2025 •

edited

Loading

Uh oh!

github-actions bot commented Nov 10, 2025 •

edited by tsullivan

Loading

Uh oh!

elasticmachine commented Nov 26, 2025

Uh oh!

elasticmachine commented Nov 26, 2025

Uh oh!

weronikaolejniczak Nov 26, 2025

Uh oh!

weronikaolejniczak Nov 26, 2025

Uh oh!

weronikaolejniczak commented Nov 28, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

		@@ -0,0 +1 @@
		Flyout system menu bar: require tile, support custom actions

	Flyout system menu bar: require tile, support custom actions
	- Flyout system menu bar: require title, support custom actions

Restore Flyout System feature in EUI #9202

Are you sure you want to change the base?

Restore Flyout System feature in EUI #9202

Uh oh!

Conversation

tsullivan commented Nov 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

New Managed Flyout System

Summary of API changes

ADDED - New Public-Facing Features

1. New Manager System

2. New Flyout Menu Component

3. resizable prop.

REMOVED - Earlier iteration of the Flyout System Feature

1. Old Session System

2. Old Child Flyout Implementation

Screenshots #

Impact to users #

BREAKING CHANGE - String Refs No Longer Supported

Flyout overlay mask z-index value update

QA

PR Mergeability / Release readiness checklist

General checklist

Uh oh!

github-actions bot commented Nov 10, 2025 • edited by tsullivan Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

elasticmachine commented Nov 26, 2025

💚 Build Succeeded

History

Uh oh!

elasticmachine commented Nov 26, 2025

💚 Build Succeeded

History

Uh oh!

weronikaolejniczak Nov 26, 2025

Choose a reason for hiding this comment

Uh oh!

weronikaolejniczak Nov 26, 2025

Choose a reason for hiding this comment

Uh oh!

weronikaolejniczak commented Nov 28, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

tsullivan commented Nov 10, 2025 •

edited

Loading

3. `resizable` prop.

Flyout overlay mask `z-index` value update

github-actions bot commented Nov 10, 2025 •

edited by tsullivan

Loading