[Visual Refresh] Update form layout `append`/`prepend` API #9014

mgadewoll · 2025-09-15T09:40:50Z

Summary

closes https://github.com/elastic/eui-private/issues/351

Important

This PR merges into a feature branch.

This PR implements two new components: EuiFormAppend and EuiFormPrepend.
These components are meant to be passed into form layout append and prepend slots to ensure a cohesive layout and styling.
These two components are meant to replace the current generic slot API, but for the initial introduction this implementation ensures a backwards compatible usage to make the update process smoother. This currently means that the previous usages of passing other components to the append/prepend slots still works and will results in mostly identical visual output.

Once consumers are updated fully, the idea is to remove the additional style rules that ensure backwards compatibility and rely on usages of EuiFormAppend and EuiFormPrepend only. Other usages would then result in unexpected visual output and indicate misusage.

Changes

Added EuiFormAppend and EuiFormPrepend components (components, docs, tests)
Added support for type="span" on EuiFormLabel to support using visual-only form labels
Updated EuiFormLabel to render a span if no htmlFor is passed
Updated EuiFormControlLayout to use EuiFormAppend and EuiFormPrepend
Updated form components EuiFormAppend/EuiFormPrepend as needed (EuiAutoRefresh, EuiColorPicker)
- ⚠️ Breaking Change: Updated EuiQuickSelectPopover in EuiSuperDatePicker to use EuiFormPrepend: This results in more restricted quickSelectButtonProps as they reflect EuiFormPrepend instead of generic EuiButtonEmpty props.
Updated EuiColorPicker to ensure id is correctly passed onto the internal EuiFormControlLayout

Why are we making this change?

💅 UI consistency: This update is part of the Visual Refresh project and it's purpose is to ensure a cohesive visual output for form layout append/prepend elements.

Screenshots #

Previous "generic slot" usage

before	after

New EuiFormAppend/Prepend usage

LIGHT	DARK

EuiAutoRefresh

before	after

EuiSuperDatePicker

before	after

EuiColorPicker

before	after

Impact to users

⚠️ The update to quickSelectButtonProps on EuiSuperDatePicker maybe cause breaking changes as it reflects a more restricted prop type for EuiFormPrepend instead of EuiButtonEmpty.

🟢 There are no usages of quickSelectButtonProps on EuiSuperDatePicker or EuiQuickSelectPopover directly in Kibana or Cloud.

ℹ️ The backwards compatibility of the changes ensures that existing Kibana usages work as expected.
We do however want to update simple Kibana usages to use EuiFormAppend/EuiFormPrepend already to drive adoption. This will be done as an additional step and linked here once available.

Deployment

💻 Kibana instance (credentials)

ℹ️ This instance currently does not have any usage updates yet.

QA

review the added EuiFormAppend/EuiFormPrepend components and their usage in append/prepend usage and ensure it matches design specs (figma, figma)
verify there is no regression for append/prepend between feature branch and staging
~~verify there is no regression for append/prepend in Amsterdam (feature branch, staging)~~
review the new and old API and verify both result in expected visual output (Storybook)
review the updated documentation
verify EuiSuperDatePicker's quick select button looks/works as expected (feature branch, staging)
verify EuiAutoRefresh looks according to new design specs (staging)
verify EuiColorPicker has no regression (feature branch, staging)

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-09-15T09:52:00Z

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

mgadewoll · 2025-09-17T08:31:40Z

ℹ️ Initial design feedback:

change append/prepend focus to :focus-visible
[-] remove added automatic <label> linking (focusing the input by clicking the append/prepend isn't wanted) - this would mean we can't use <label> at all and change how it works currently towards using e.g. aria-labelledby instead
- for semantics and Accessibility it's correct to link <label> elements. This has already been done before, only the examples did not have an id applied that would trigger the linking. Imho it's correct to showcase proper id usage in the docs.
remove the testing stories that showcase the old API

mgadewoll · 2025-12-12T16:46:45Z

ℹ️ I rebased this branch and ~~changed the target merge branch to main~~ (this branch and the target branch were very much outdated 💀)
This branch already contains the additional button changes from #8948 and we can create a QA environment anyway from this branch (with local packages or snapshot release from a temporary branch)

EDIT: The branch was rebased again with the reinstated feature branch feat/visual-refresh-append-prepend-updates, as we'll be adding additional design updates to form append/prepends.

- updates EuiFormControlLayout by adding a context to share props - updates EuiFormLabel to support visual-only renders as span element

- aligns styling with EuiFormAppendPrepend styles

mgadewoll · 2026-01-05T15:45:13Z

packages/eui/src/components/form/form_label/form_label.tsx

        {children}
      </legend>
    );
+  } else if (type === 'span') {


💭 I'm wondering if we also want to update this to else if (type === 'span' || !htmlFor) to prevent rendering a <label> when the input linking is not applied as a <label> would expect a relation to a linked element.

This would likely affect more tests on Kibana side, as I'm not sure how diligently the inputId is applied.

I think it makes sense to check for !htmlFor. We're already introducing changes that will likely affect Kibana tests, so as long as this wouldn't result in breaking unreasonable number of them that would need manual updates, I'd say we should go with it

Considering this will already be a breaking change and we'll have a QA phase, I think it should be reasonable to include the update in the overall append/prepend update feature. We'll merge this into a feature branch anyway, worst case we can revert if it causes to much trouble.

Added in 4da2bbe.
I also updated the docs to try and explain the different scenarios more clearly.

ℹ️ Fyi, the potential test failures I'd expect here are:

snapshots (<span> instead of <label> element is rendered)

selectors not available if a test checks for a label role

As this is on the EuiFormLabel component, it could happen across all of Kibana, it's not directly related to the Append/Prepend change.

...ages/eui/src/components/form/form_control_layout/append_prepend/form_append_prepend.test.tsx

packages/eui/src/components/form/form_control_layout/form_control_layout.tsx

- clarifies the different render outputs and ways to properly label append/prepend

tkajtoch · 2026-01-06T11:46:25Z

Thank you for addressing my comments! Code changes look good, I'm currently going through QA steps to verify everything. I opened #9293 to have a testing environment for the feature branch

elasticmachine · 2026-01-06T12:19:14Z

💚 Build Succeeded

History

💚 Build #2317 succeeded 0e50bb0
💚 Build #2305 succeeded f8704b1
💚 Build #2303 succeeded bc1e825
💚 Build #2298 succeeded 8c1081c
💚 Build #2297 succeeded dde1d94
💚 Build #2206 succeeded 6dc14e7

cc @mgadewoll

elasticmachine · 2026-01-06T12:37:54Z

💚 Build Succeeded

Buildkite Build
Commit: 40eb3a1

History

💚 Build #5509 succeeded 0e50bb0
💚 Build #5500 succeeded f8704b1
💚 Build #5495 succeeded 8c1081c
💚 Build #5416 succeeded 6dc14e7
💚 Build #5211 succeeded e870cba
💚 Build #4732 succeeded e870cba

cc @mgadewoll

tkajtoch

Code changes look great, QA passed. LGTM

mgadewoll self-assigned this Sep 15, 2025

mgadewoll added visual refresh breaking change PRs with breaking changes. (Don't delete - used for automation) labels Sep 15, 2025

mgadewoll force-pushed the inputs/351-refactor-append-prepend branch from e870cba to 6dc14e7 Compare December 12, 2025 16:37

mgadewoll changed the base branch from feat/visual-refresh-append-prepend-updates to main December 12, 2025 16:43

mgadewoll force-pushed the inputs/351-refactor-append-prepend branch from 6dc14e7 to dde1d94 Compare January 5, 2026 10:00

mgadewoll changed the base branch from main to feat/visual-refresh-append-prepend-updates January 5, 2026 10:00

mgadewoll added 12 commits January 5, 2026 11:23

feat: add EuiFormAppend and EuiFormPrepend

66146dc

- updates EuiFormControlLayout by adding a context to share props - updates EuiFormLabel to support visual-only renders as span element

refactor: use EuiFormAppend/Prepend in EuiFormControlLayout

8f31684

refactor: update form components to use EuiFormAppend/Prepend

0df0c2e

test: update snapshots

c70a8a7

docs(storybook): update stories to use EuiFormAppend/Prepend

d33ce25

docs: add/update docs related to EuiFormAppend/Prepend

4beeb6a

styles: udpate font-weight JSDoc

ee78db3

test(vrt): add/update reference images

2cdb053

chore: add chagnelog

61f1e3d

refactor: show append/prepend focus only on focus-visible

7e55f1f

chore: mark stories for removal, cleanup vrt images

6f2a080

test: update snapshots

8c1081c

mgadewoll force-pushed the inputs/351-refactor-append-prepend branch from dde1d94 to 8c1081c Compare January 5, 2026 10:24

mgadewoll added 2 commits January 5, 2026 13:17

chore: cleanup

bc1e825

refactor: update legacy append/prepend padding overrides

f8704b1

- aligns styling with EuiFormAppendPrepend styles

mgadewoll marked this pull request as ready for review January 5, 2026 14:05

mgadewoll requested a review from a team as a code owner January 5, 2026 14:05

mgadewoll commented Jan 5, 2026

View reviewed changes

tkajtoch self-requested a review January 5, 2026 17:24

tkajtoch reviewed Jan 5, 2026

View reviewed changes

...ages/eui/src/components/form/form_control_layout/append_prepend/form_append_prepend.test.tsx Outdated Show resolved Hide resolved

tkajtoch reviewed Jan 5, 2026

View reviewed changes

packages/eui/src/components/form/form_control_layout/form_control_layout.tsx Show resolved Hide resolved

mgadewoll added 4 commits January 6, 2026 10:45

refactor: update form control layout side render condition syntax

48f282b

test: update test syntax

a182648

refactor: render span element for EuiFormLabel if no id is set

4da2bbe

docs: rewrite append/prepend label docs

0e50bb0

- clarifies the different render outputs and ways to properly label append/prepend

mgadewoll force-pushed the inputs/351-refactor-append-prepend branch from 377d296 to 0e50bb0 Compare January 6, 2026 10:01

chore: update changelog

40eb3a1

tkajtoch approved these changes Jan 6, 2026

View reviewed changes

mgadewoll merged commit fee46b7 into elastic:feat/visual-refresh-append-prepend-updates Jan 7, 2026
4 checks passed

[Visual Refresh] Update form layout append/prepend API #9014

[Visual Refresh] Update form layout append/prepend API #9014

Uh oh!

Conversation

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

Uh oh!

Summary

Changes

Why are we making this change?

Screenshots #

Impact to users

Deployment

QA

General checklist

Uh oh!

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

Uh oh!

Uh oh!

mgadewoll commented Sep 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

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

Uh oh!

Uh oh!

mgadewoll Jan 5, 2026

Choose a reason for hiding this comment

Uh oh!

tkajtoch Jan 5, 2026

Choose a reason for hiding this comment

Uh oh!

mgadewoll Jan 6, 2026

Choose a reason for hiding this comment

Uh oh!

mgadewoll Jan 6, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

tkajtoch commented Jan 6, 2026

Uh oh!

elasticmachine commented Jan 6, 2026

💚 Build Succeeded

History

Uh oh!

elasticmachine commented Jan 6, 2026

💚 Build Succeeded

History

Uh oh!

tkajtoch left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

[Visual Refresh] Update form layout `append`/`prepend` API #9014

[Visual Refresh] Update form layout `append`/`prepend` API #9014

mgadewoll commented Sep 15, 2025 •

edited

Loading

github-actions bot commented Sep 15, 2025 •

edited by mgadewoll

Loading

mgadewoll commented Sep 17, 2025 •

edited

Loading

mgadewoll commented Dec 12, 2025 •

edited

Loading