[EuiFlyout] Forward ref to the flyout components

[weronikaolejniczak]

Summary

Important

This is a high-priority PR. It should be reviewed, tested and released as soon as possible.

• Wrapped EuiFlyoutChild, EuiFlyoutMain and EuiFlyoutManaged with forwardRef and passed it to EuiFlyoutComponent.
• Passed ref in EuiFlyout to EuiFlyoutChild and EuiFlyoutMain.
• Added unit tests to make sure when session is used, ref is not null.

Why are we making this change?

Resolves #9313

When session flyouts are used, the focus doesn't properly move to the flyout content, thus creating a big accessibility issue and potentially breaking focus-reliant functionality on consumer side. The reason was flyout components (EuiFlyoutChild, EuiFlyoutMain etc.) weren't wrapped with forwardRef and EuiFlyout didn't pass the ref. It came back as null.

It has been reported internally by Kibana teams. Unblocks elastic/kibana#246719.

Screenshots #

In Discover

	Before	After
Screen recording	Screen.Recording.2026-01-15.at.12.38.54.mov	Screen.Recording.2026-01-15.at.12.31.05.mov
Description	Navigation between documents doesn't work, focus doesn't move to the flyout content, arrow keys cause navigation only in the data grid	Navigation between documents works, focus moves to the flyout content, you can navigate it with arrow keys along with data grid

Impact to users

🟢 This is a bug fix. It's not a breaking change. No changes needed on consumer side. No visual changes were made.

QA

Specific checklist

• Storybook
  • navigate within the flyout with the keyboard
  • open the main flyout
  • open the child flyout
  • try resizing the flyout
  • resize the browser window, the flyout should switch between overlay and push as expected
  • make sure there's no regression compared to prod
• Unified Doc Viewer focus management is correct and using arrow keys for navigating between documents works

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)
  • If the changes unblock an issue in a different repo, smoke tested carefully (see Testing EUI features in Kibana ahead of time)
• 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)

[weronikaolejniczak]

The reason we use useState here is because of useResizeObserver hook that accepts a DOM element (container) as an argument and uses useEffect to attach the observer, see:

eui/packages/eui/src/components/observer/resize_observer/resize_observer.tsx

Lines 92 to 100 in 1bddb4c

	useEffect(() => {
	if (container != null) {
	const observer = makeResizeObserver(container, ([entry]) => {
	const { inlineSize, blockSize } = entry.borderBoxSize[0];
	setSize({
	width: inlineSize,
	height: blockSize,
	});
	});

If we use useRef, flyoutRef.current is null during the initial render. That means when the component mounts and the ref is populated, useRef does not trigger a re-render and the useResizeObserver is not re-evaluated so the observer fails to attach to the element.

By using useState and "callback ref" pattern we basically ensure that the component will re-render and pass the actual el to the observer.

I memoized the ref array before passing to useCombinedRefs to minimize unnecessary updates.

[elasticmachine]

💚 Build Succeeded

• Buildkite Build
• Commit: 7a93b47
• Documentation website
• Storybook

History

• 💚 Build #2432 succeeded 09359b4

cc @weronikaolejniczak

[elasticmachine]

💚 Build Succeeded

• Buildkite Build
• Commit: 7a93b47

cc @weronikaolejniczak

[mgadewoll]

Thanks for adding tests! 🙏

[mgadewoll]

[no change request, unrelated to the changes]

ℹ️ While testing I did encounter an unexpected behavior but it's unrelated to the changes in this PR as it's reproducible also on production.
When a child flyout is open and if the flyout is resizable the content container does not update accordingly on smaller viewports. Instead of tracking the visible (child) flyout width, it's still based on the underlying main flyout width.

Screen.Recording.2026-01-15.at.16.31.14.mov

[mgadewoll]

🟢 All changes are LGTM.
The flyout functionality works as expected and there is no regression with production.
Thanks for tackling this bug fix! 💪

[weronikaolejniczak]

@mgadewoll That's a very good catch, I was able to reproduce.

The reason why this happens is when the flyouts are stacked (because of small viewport), the main flyout (push type) continues to push the main content based on its own width, even if it's underneath the child flyout and not visible. That child flyout width is different (especially if resized) so it yields that content offset.

The fix is very simple, it's just using the child flyout's width for the push padding calculation when in stacked layout mode and it's the main flyout. I have the code prepared and it seems to be working well:

Kapture.2026-01-16.at.10.23.06.mp4

It's not urgent while this PR is, so I'll push it on a separate one.

Thank you for the fast review, Lene! 🙏🏻

EDIT: #9322