Restore Flyout System feature in EUI

[tsullivan]

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:

1. 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>

2. 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

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]

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

[weronikaolejniczak]

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.

[elasticmachine]

💚 Build Succeeded

• Buildkite Build
• Commit: 65f9b06
• Documentation website
• Storybook

History

• 💚 Build #2140 succeeded 1ba4423
• 💚 Build #2084 succeeded 451e83d
• 💚 Build #2071 succeeded 50647c5
• 💚 Build #2070 succeeded 50647c5
• 💚 Build #2067 succeeded 90731e5
• 💚 Build #2059 succeeded e9787a9

cc @tsullivan @tkajtoch

[tkajtoch]

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

This issue seems to be related to the same EuiPortal issue and isn't caused by any of the changes introduced here. I dug into it a little and have some ideas on why this might be happening, but nothing concrete yet. Let's fix it separately since changing EuiPortal would need lots of testing in EUI and Kibana.

[elasticmachine]

💚 Build Succeeded

• Buildkite Build
• Commit: 65f9b06

History

• 💚 Build #5370 succeeded 1ba4423
• 💚 Build #5329 succeeded 451e83d
• 💚 Build #5318 succeeded 50647c5
• 💚 Build #5317 succeeded 90731e5
• 💔 Build #5311 failed e9787a9
• 💚 Build #5210 succeeded cbb5862

cc @tsullivan @tkajtoch

[tkajtoch]

I reviewed and tested all changes included in this PR. LGTM