Feature: Flyout System [Beta] #9068

tsullivan · 2025-09-30T14:38:56Z

New Managed Flyout System

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_9068/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_9068/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_9068/docs/components/containers/flyout/#resizable-flyout
New optional prop	EuiFlyout	`onResize?`	Documentation: https://eui.elastic.co/pr_9068/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_9068/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_9068/docs/components/containers/flyout/#flyout-menu
New optional prop	EuiFlyout	`hasChildBackground?`	Documentation: https://eui.elastic.co/pr_9068/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 - 1 making it more predictable.

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)

Co-authored-by: Tim Sullivan <[email protected]> Co-authored-by: Timothy Sullivan <[email protected]> Co-authored-by: Weronika Olejniczak <[email protected]>

…ions in top menu (#8997) Co-authored-by: Tomasz Kajtoch <[email protected]>

…ransition animations of managed flyouts (#9015) Co-authored-by: Arturo Castillo Delgado <[email protected]> Co-authored-by: Tim Sullivan <[email protected]>

Co-authored-by: Clint Andrew Hall <[email protected]> Co-authored-by: Weronika Olejniczak <[email protected]> Co-authored-by: Tomasz Kajtoch <[email protected]>

…nu title ID (#9073)

)

…ity (#9094)

elasticmachine · 2025-10-14T14:00:03Z

💚 Build Succeeded

History

💚 Build #1503 succeeded ff3c788
💚 Build #1502 succeeded ff3c788
💚 Build #1499 succeeded 1e403fa
💚 Build #1498 succeeded 1e403fa
💚 Build #1447 succeeded e252ac2
💚 Build #1438 succeeded 75528cf

cc @tsullivan

… use for child flyouts only (#9056) Co-authored-by: Tim Sullivan <[email protected]>

Co-authored-by: Timothy Sullivan <[email protected]> Co-authored-by: Tim Sullivan <[email protected]>

JasonStoltz · 2025-10-15T20:29:26Z

@tsullivan @tkajtoch

I've added a PR mergeability / release readiness checklist to the PR description. Please make sure everything listed there is accounted for before merging this PR to main.

tkajtoch · 2025-10-15T21:58:53Z

packages/eui/src/components/flyout/flyout.test.tsx

 }));

 describe('EuiFlyout', () => {
+  // TODO: Add `maskProps` to `childProps` again when EuiOverlayMask


@tkajtoch fix this

Addressed in #9155

tkajtoch · 2025-10-15T22:05:57Z

packages/eui/src/components/flyout/use_open_state.ts

+
+export type EuiFlyoutOpenState = 'opening' | 'open';
+
+export const useEuiFlyoutOpenState = () => {


@tkajtoch remove unused hook

Addressed in #9155

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

Co-authored-by: Timothy Sullivan <[email protected]> Co-authored-by: Tim Sullivan <[email protected]>

…rom interacting with the Flyout System (#9124) Co-authored-by: Timothy Sullivan <[email protected]>

JasonStoltz · 2025-10-27T21:32:33Z

Thanks for updating this issue with the "Summary of API changes" table and handling the other release readiness items. It looks good to me on that front 👍

tsullivan · 2025-10-28T00:42:04Z

/ci

tsullivan · 2025-10-28T00:44:52Z

Also, quick question -- as a user, when I see this: https://eui.elastic.co/pr_9068/docs/components/containers/flyout/#flyout-menu ... is this something that I should use generally or is this just available for use in managed Flyouts? And how does it correspond to flyoutMenuProps? As a user looking at these docs, I'm super confused.

@JasonStoltz I have updated the docs on EuiFlyoutMenu, so it should be clear now. It is a private component, and controlled through the flyoutMenuProps that is passed to `EuiFlyout.

32edff0

JasonStoltz · 2025-10-28T12:51:55Z

@tsullivan Thank you Tim! From the review point of view, I'm good with this in terms of release. I didn't actually approve the PR because I haven't looked at the code -- someone else from the EUI team can provide that.

elasticmachine · 2025-10-28T17:25:24Z

💚 Build Succeeded

History

💚 Build #1736 succeeded 3bd96e3
💚 Build #1734 succeeded 29d5609
💚 Build #1733 succeeded 29d5609
💚 Build #1724 succeeded 0e4460c
💚 Build #1720 succeeded 32edff0
💚 Build #1719 succeeded 32edff0

cc @tsullivan

elasticmachine · 2025-10-28T17:39:18Z

💚 Build Succeeded

Buildkite Build
Commit: 9bd2d75

History

💚 Build #5060 succeeded 29d5609
💚 Build #5052 succeeded 0e4460c
💔 Build #5049 failed 32edff0
💚 Build #5046 succeeded e24da0c
💚 Build #5036 succeeded f00a6a4
💚 Build #5030 succeeded 87af8c3

cc @tsullivan

ryankeairns · 2025-10-28T22:01:45Z

Feedback on docs

1. Title overflows menu bar

Since this is a main flyout, the title should be passed to the EuiFlyoutHeader section (we discussed this in Slack; perhaps the API was changed and the docs were not?)
For child flyouts that can have a title in this place, we should use truncation to avoid overflowing

2. Page structure

Instead of a separate page - which also makes the parent accordion a page - we could include the session management section in the same/main flyout page. This could be under Usage or under Guidelines (see the Panel page for an example)

ryankeairns · 2025-10-28T22:08:36Z

Feedback on docs

1. Title overflows menu bar

Since this is a main flyout, the title should be passed to the EuiFlyoutHeader section (we discussed this in Slack; perhaps the API was changed and the docs were not?)

For child flyouts that can have a title in this place, we should use truncation to avoid overflowing

**2. Page structure**

Instead of a separate page - which also makes the parent accordion a page - we could include the session management section in the same/main flyout page. This could be under Usage or under Guidelines (see the Panel page for an example)

This is addressed in #9150

tkajtoch · 2025-10-29T12:13:29Z

We can disregard the changelog CI step reporting waiting for status to be reported. We updated it earlier this week, and it behaves buggy. I manually confirmed we have all the required changelog files.

I'm wrapping up my final QA against Kibana and should approve the PR within the next few hours.

tsullivan · 2025-10-29T15:45:04Z

Page structure
Instead of a separate page - which also makes the parent accordion a page - we could include the session management section in the same/main flyout page. This could be under Usage or under Guidelines (see the Panel page for an example)

Thanks @ryankeairns I have filed this to work on as a separate change. Hope that is OK.

tkajtoch · 2025-10-30T16:05:32Z

I have finished testing the changes against Kibana and found no regressions. There are a few places where Kibana overrides EuiFlyout z-index styles to render the AI Assistant flyout on top of another open flyout (sounds familiar, huh? see an example), but these will be adjusted in next week's upgrade PR which I'm responsible for.

LGTM 🚢

This reverts commit e500915.

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]>

tsullivan and others added 9 commits September 17, 2025 18:19

Add FlyoutSystemMenu component (#8851)

4c698c4

[flyouts] Developer API + sessions (#8939)

8f1370b

Co-authored-by: Tim Sullivan <[email protected]> Co-authored-by: Timothy Sullivan <[email protected]> Co-authored-by: Weronika Olejniczak <[email protected]>

[Flyout System] Support size="fill" (#8982)

baaa271

[Flyout System] Support resizing flyouts (#8999)

225db60

[Flyout system] Improve flyout animations (#9025)

ecd3535

[Flyout System] require title for session flyouts, support custom act…

d811dac

…ions in top menu (#8997) Co-authored-by: Tomasz Kajtoch <[email protected]>

Make the resizable hook inert when resizable is not enabled (#9052)

ab3d37d

[Flyout System] Integrate unmanaged EuiFlyout animations with state t…

a8c300b

…ransition animations of managed flyouts (#9015) Co-authored-by: Arturo Castillo Delgado <[email protected]> Co-authored-by: Tim Sullivan <[email protected]>

[Flyout System] Add managed history controls (#9003)

faf365c

Co-authored-by: Clint Andrew Hall <[email protected]> Co-authored-by: Weronika Olejniczak <[email protected]> Co-authored-by: Tomasz Kajtoch <[email protected]>

tsullivan self-assigned this Sep 30, 2025

tsullivan added skip-changelog Use on PRs to skip changelog requirement (Don't delete - used for automation) and removed skip-changelog Use on PRs to skip changelog requirement (Don't delete - used for automation) labels Sep 30, 2025

tsullivan added 3 commits October 3, 2025 09:34

[Flyout System] Clean up storybooks (#9070)

4538a3b

[Flyout System] Automatic aria-labelledby referencing the EuiFlyoutMe…

75528cf

…nu title ID (#9073)

[Flyout System] Allow flyout size to be undefined, default to ‘m’ (#9072

e252ac2

)

tsullivan changed the title ~~Feature: Flyout System~~ Feature: Flyout System [Beta] Oct 6, 2025

tsullivan and others added 3 commits October 10, 2025 14:38

[Flyout System] Improve validation and error logging (#9091)

1e403fa

[Flyout System] Remove isOpen prop (#9083)

ff3c788

[Flyout System] improve size validation flexibility and bidirectional…

3cc1e53

…ity (#9094)

paulinashakirova and others added 3 commits October 15, 2025 07:46

feat: Add a new boolean childBackgroundShaded prop to the Flyout to…

33f76da

… use for child flyouts only (#9056) Co-authored-by: Tim Sullivan <[email protected]>

Merge branch 'main' into feat/flyout-system

13d1386

[Flyout System] Add the flyout overlay mask back (#9077)

801ecc6

Co-authored-by: Timothy Sullivan <[email protected]> Co-authored-by: Tim Sullivan <[email protected]>

tkajtoch reviewed Oct 15, 2025

View reviewed changes

packages/eui/src/components/overlay_mask/overlay_mask.tsx Show resolved Hide resolved

clintandrewhall and others added 3 commits October 15, 2025 15:32

[fix] Keep Flyout Manager sync'd across React roots. (#9075)

96cc060

Co-authored-by: Timothy Sullivan <[email protected]> Co-authored-by: Tim Sullivan <[email protected]>

[flyout system/fix] Breaking: Prevent default configuration flyouts f…

b5267a4

…rom interacting with the Flyout System (#9124) Co-authored-by: Timothy Sullivan <[email protected]>

[Flyout System] Set ownFocus=false in storybooks (#9123)

848b26a

tsullivan force-pushed the feat/flyout-system branch from 3934a1f to d199818 Compare October 27, 2025 19:41

[Flyout System] Improve docs of EuiFlyoutMenu

32edff0

tsullivan force-pushed the feat/flyout-system branch from d199818 to 32edff0 Compare October 27, 2025 20:19

Merge branch 'main' into feat/flyout-system

0e4460c

tsullivan requested a review from tkajtoch October 28, 2025 16:36

add eui-theme-* changelog files

3bd96e3

tsullivan force-pushed the feat/flyout-system branch from 29d5609 to 3bd96e3 Compare October 28, 2025 16:44

[Flyout System] Cleanup TODOs (#9155)

9bd2d75

ryankeairns self-requested a review October 28, 2025 21:55

JasonStoltz mentioned this pull request Oct 29, 2025

Regular flyout should work with the push flyout #7443

Closed

tkajtoch approved these changes Oct 30, 2025

View reviewed changes

tkajtoch merged commit e500915 into main Oct 30, 2025
8 checks passed

tkajtoch deleted the feat/flyout-system branch October 30, 2025 16:10

tsullivan restored the feat/flyout-system branch October 30, 2025 16:13

tsullivan deleted the feat/flyout-system branch October 30, 2025 16:14

tkajtoch added a commit to tkajtoch/eui that referenced this pull request Nov 4, 2025

Revert "Feature: Flyout System [Beta] (elastic#9068)"

53abcd4

This reverts commit e500915.

This was referenced Nov 5, 2025

Restore Flyout System feature in EUI #9178

Merged

Restore Flyout System feature in EUI #9202

Draft


		export type EuiFlyoutOpenState = 'opening' \| 'open';

		export const useEuiFlyoutOpenState = () => {

Feature: Flyout System [Beta] #9068

Feature: Flyout System [Beta] #9068

Uh oh!

Conversation

tsullivan commented Sep 30, 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!

elasticmachine commented Oct 14, 2025

💚 Build Succeeded

History

Uh oh!

JasonStoltz commented Oct 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

tkajtoch Oct 15, 2025

Choose a reason for hiding this comment

Uh oh!

tkajtoch Oct 28, 2025

Choose a reason for hiding this comment

Uh oh!

tkajtoch Oct 15, 2025

Choose a reason for hiding this comment

Uh oh!

tkajtoch Oct 28, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

JasonStoltz commented Oct 27, 2025

Uh oh!

tsullivan commented Oct 28, 2025

Uh oh!

tsullivan commented Oct 28, 2025

Uh oh!

JasonStoltz commented Oct 28, 2025

Uh oh!

elasticmachine commented Oct 28, 2025

💚 Build Succeeded

History

Uh oh!

elasticmachine commented Oct 28, 2025

💚 Build Succeeded

History

Uh oh!

ryankeairns commented Oct 28, 2025

Feedback on docs

Uh oh!

ryankeairns commented Oct 28, 2025

Feedback on docs

Uh oh!

tkajtoch commented Oct 29, 2025

Uh oh!

tsullivan commented Oct 29, 2025

Uh oh!

tkajtoch commented Oct 30, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

8 participants

tsullivan commented Sep 30, 2025 •

edited

Loading

3. `resizable` prop.

Flyout overlay mask `z-index` value update

JasonStoltz commented Oct 15, 2025 •

edited

Loading