[EuiDataGrid] Support rendering the header optionally #9281

mgadewoll · 2025-12-18T13:59:12Z

Summary

Closes https://github.com/elastic/eui-private/issues/475
Closes #9000

This PR updates EuiDataGrid to add support for a conditionally rendered header element via a new prop: headerVisibility. The naming is chosen to be in line with the existing toolbarVisibility for the external facing API.

prop	type	default value	description
`headerVisibility`	`boolean`	`true`	Controls if the datagrid header element is rendered or not

Accessibility

Generally not rendering the header element is not adviced for semantic tables, as its required for providing contextual information to screen readers.
The current implementation of EuiDataGrid adds the contextual information as screen reader only text to each cell which ensures that accessibility is kept as is.

Screen.Recording.2025-12-18.at.09.09.155.mov

Why are we making this change?

✨ Feature request: Serving a Kibana feature request.

Screenshots #

Screen.Recording.2025-12-18.at.15.07.11.mov

light	dark

Usage with headerVisibility=false + toolbarVisibility=false

light	dark

Impact to users

🟢 No updates required on consumer side. This is a new, opt-in feature.

QA

test the new headerVisibility on EuiDataGrid and verify it works as expected (ensure to test in different combinations: with toolbarvisibility with different border styles etc
verify there is otherwise no regression with production
verify that cells have the correct contextual header information appended for screen readers

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)

- the getRow method may return undefined

elasticmachine · 2025-12-18T17:22:39Z

💚 Build Succeeded

History

💚 Build #2260 succeeded 92feee7
💔 Build #2259 failed 33a1a55

cc @mgadewoll

elasticmachine · 2025-12-18T17:36:43Z

💚 Build Succeeded

Buildkite Build
Commit: be49e96

History

💔 Build #5462 failed 92feee7

cc @mgadewoll

weronikaolejniczak · 2025-12-31T10:01:50Z

packages/eui/src/components/datagrid/body/data_grid_body.styles.ts

+      /* hack to prevent visible flickering on the single initial render when rows are created.
+      opacity > 0 ensure the element is anyway present in the DOM */
+      .euiDataGridRowCell--isMounting:where(
+          :not(.euiDataGridHeaderCell, .euiDataGridFooterCell)
+        ) {
+        opacity: 0.01;
+      }


I couldn't reproduce any flickering on the initial render. Could you provide more details how to test this?

If the change is not related to the conditional rendering of the header in any way (e.g. it doesn't make the flickering issue significantly worse), I'd extract it to a separate PR with an appropriate description, steps to reproduce, pointers what to test for and a link to related issues (if they exist).

weronikaolejniczak · 2025-12-31T10:12:08Z

packages/eui/src/components/datagrid/body/data_grid_body_virtualized.tsx

      const wrapperDimensions = useResizeObserver(wrapperRef.current);
      const outerGridRef = useRef<HTMLDivElement | null>(null); // container that becomes scrollable
-      const innerGridRef = useRef<HTMLDivElement | null>(null); // container sized to fit all content
+      const innerGridRef = useRef<HTMLDivElement | null>(null);


Why was this comment removed?

weronikaolejniczak

The showHeader code changes look good 👍🏻 I shared some doubts in separate comments.

Testing notes

Header and toolbar visibility (tested here)

Toolbar and header display as expected. gridStyle.border is default here, so "all" for all 4 cases.

✅ default `headerVisiblity={true}` & default `toolbarVisibility`

	HCM off	HCM on
Light mode
Dark mode

✅ default `headerVisiblity={true}` & `toolbarVisibility={false}`

	HCM off	HCM on
Light mode
Dark mode

✅ `headerVisiblity={false}` & `toolbarVisibility={false}`

	HCM off	HCM on
Light mode
Dark mode

✅ `headerVisiblity={false}` & default `toolbarVisibility`

	HCM off	HCM on
Light mode
Dark mode

Different `gridStyle`, focusing on `border` (docs, tested here)

There are no missing or doubled borders. Tested in light mode with HCM off.

✅ `horizontal`

	default `headerVisibility={true}`	`headerVisibility={false}`
default `toolbarVisibility`
`toolbarVisibility={false}`

✅ `none`

	default `headerVisibility={true}`	`headerVisibility={false}`
default `toolbarVisibility`
`toolbarVisibility={false}`

Screen reader output (tested here)

Because we enrich each cell with screen-reader-only text, not rendering the header doesn't have detrimental effect to a11y. Actually, it yields better screen reader announcements because they are not polluted by the column cell announcements (e.g. "Press the Enter key to view this column's actions" when the Enter key is already mapping to "expanding the cell"). In the JAWS case, the column header is repeated if the header is present.

💡 It could be a nice opportunity to think about:

#8449

Is there an easy way we could include this change?

✅ (MacOS) VoiceOver + MacOS

With header	Without header
Kapture.2025-12-31.at.12.11.57.mp4	Kapture.2025-12-31.at.12.09.42.mp4

💭 The only difference seems to be that if the header is present, the number of columns and rows is read out. If it's not present, that data is omitted. And we do pass aria-rowcount directly. Not sure why that is.

✅ (Win) NVDA + Firefox

With header	Without header
Kapture.2025-12-31.at.12.26.23.mp4	Kapture.2025-12-31.at.12.23.20.mp4

💭 (out of scope) The NVDA + data grid experience is very confusing due to browse mode. Only once I browse to a specific cell with arrow down and tab, can I then navigate with the arrow keys. Do you know why that is and if it's something we can improve?

✅ (Win) JAWS + Chrome

🔈 With header	🔈 Without header
Kapture.2025-12-31.at.12.35.00.mp4	Kapture.2025-12-31.at.12.32.23.mp4

Potential prod regression

Based on code changes, I tested these potential regression spots:

✅ there are no missing or double borders
✅ on initial render, the data grid displays correctly both with and without the header
✅ when dynamically toggling headerVisibility, the scroll offset is applied correctly and there is no layout shift or jumpiness
✅ there are no renderCustomGridBody usages that access headerRow property without checking for null (no such cases in Kibana)

I couldn't verify this point because I cannot reproduce the issue, even with simulated CPU throttling:

❓ verified the isMounting logic prevents flickering and doesn't leave cells in an invisible state

Personally, if it's not caused or significantly worsened by the changes on the PR, I'd move it to a separate PR with clear steps to reproduce.

mgadewoll self-assigned this Dec 18, 2025

mgadewoll force-pushed the datagrid/optional-header branch 2 times, most recently from 33a1a55 to 92feee7 Compare December 18, 2025 14:24

mgadewoll added 5 commits December 18, 2025 17:58

refactor(dataGrid): add support for optional header

da69ab9

test: update unit test

aff595e

- the getRow method may return undefined

docs(storybook): add story

fee21fd

test(vrt): update reference images

db73871

chore: add changelog

be49e96

mgadewoll force-pushed the datagrid/optional-header branch from 92feee7 to be49e96 Compare December 18, 2025 17:04

mgadewoll marked this pull request as ready for review December 19, 2025 10:00

mgadewoll requested a review from a team as a code owner December 19, 2025 10:00

JasonStoltz mentioned this pull request Dec 22, 2025

[EuiDataGrid] Create headerless option #9000

Open

weronikaolejniczak self-requested a review December 29, 2025 10:22

weronikaolejniczak reviewed Dec 31, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

[EuiDataGrid] Support rendering the header optionally #9281

[EuiDataGrid] Support rendering the header optionally #9281

Uh oh!

mgadewoll commented Dec 18, 2025 •

edited by weronikaolejniczak

Loading

Uh oh!

elasticmachine commented Dec 18, 2025

Uh oh!

elasticmachine commented Dec 18, 2025

Uh oh!

weronikaolejniczak Dec 31, 2025

Uh oh!

weronikaolejniczak Dec 31, 2025

Uh oh!

weronikaolejniczak left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

[EuiDataGrid] Support rendering the header optionally #9281

Are you sure you want to change the base?

[EuiDataGrid] Support rendering the header optionally #9281

Uh oh!

Conversation

mgadewoll commented Dec 18, 2025 • edited by weronikaolejniczak Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Accessibility

Why are we making this change?

Screenshots #

Impact to users

QA

General checklist

Uh oh!

elasticmachine commented Dec 18, 2025

💚 Build Succeeded

History

Uh oh!

elasticmachine commented Dec 18, 2025

💚 Build Succeeded

History

Uh oh!

weronikaolejniczak Dec 31, 2025

Choose a reason for hiding this comment

Uh oh!

weronikaolejniczak Dec 31, 2025

Choose a reason for hiding this comment

Uh oh!

weronikaolejniczak left a comment

Choose a reason for hiding this comment

Testing notes

Header and toolbar visibility (tested here)

✅ default headerVisiblity={true} & default toolbarVisibility

✅ default headerVisiblity={true} & toolbarVisibility={false}

✅ headerVisiblity={false} & toolbarVisibility={false}

✅ headerVisiblity={false} & default toolbarVisibility

Different gridStyle, focusing on border (docs, tested here)

✅ horizontal

✅ none

Screen reader output (tested here)

✅ (MacOS) VoiceOver + MacOS

✅ (Win) NVDA + Firefox

✅ (Win) JAWS + Chrome

Potential prod regression

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

mgadewoll commented Dec 18, 2025 •

edited by weronikaolejniczak

Loading

✅ default `headerVisiblity={true}` & default `toolbarVisibility`

✅ default `headerVisiblity={true}` & `toolbarVisibility={false}`

✅ `headerVisiblity={false}` & `toolbarVisibility={false}`

✅ `headerVisiblity={false}` & default `toolbarVisibility`

Different `gridStyle`, focusing on `border` (docs, tested here)

✅ `horizontal`

✅ `none`