Add EmptyState component to @wordpress/ui#74719
Merged
Conversation
|
The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message. To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook. |
|
Size Change: 0 B Total Size: 7.66 MB ℹ️ View Unchanged
|
compound component with Root, Visual, Icon, Title, Description, Actions
remove docblock comments, use semantic CSS tokens
retrofox
force-pushed
the
update/ui-emptystate-component
branch
from
d48ee8f to
cf55b85
Compare
t-hamano
added
[Type] Enhancement
|
Flaky tests detected in 3a93b01. 🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/23353966154
|
Member
|
@retrofox Can you check the lint errors on this one? I'd be curious if we can demonstrate a use-case for this in Gutenberg. I feel like this is a perfect fit for |
ciampo
force-pushed
the
update/ui-emptystate-component
branch
from
cf55b85 to
992df0d
Compare
Contributor
|
@retrofox I took over this PR and pushed a couple of small commits (including lint fixes). @aduth re. whether this component belongs to the Having said that, I believe there is a need for such component across wordpress-related UIs. Maybe it could make sense to start moving it to dataviews and only abstract it if necessary? cc @WordPress/gutenberg-components @WordPress/gutenberg-design for feedback on the matter. |
|
The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message. To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook. |
retrofox
commented
Feb 4, 2026
Member
I'm a little less torn on it being part of |
ciampo
force-pushed
the
update/ui-emptystate-component
branch
from
992df0d to
85a2ea7
Compare
Contributor
|
@WordPress/gutenberg-design maybe you can help us understand better if there's a real need for this component to be part of the DS, where it's going to used, and what's in your opinion the best place for it — dataviews, ui package, etc |
Contributor
|
Starting in DataViews seems reasonable to me. I'm struggling to think of a use case for |
|
I was just exploring it for the Analytics section, but it might not be needed actually. |
Member
I'd prefer this too. "If can live somewhere else, it should" might be my rule of thumb for |
Contributor
|
Let's make sure we have a clear understanding of the usages of |
ciampo
added
the
[Status] Blocked
retrofox
force-pushed
the
update/ui-emptystate-component
branch
from
85a2ea7 to
378689c
Compare
Contributor
Author
No really, we are using this component in different contexts. Dashboard widget 
Dashboards 
|
Member
|
If not in components, then In that case, it might make sense to also add prop in 
|
Contributor
Author
It was defined in the design, just in case. |
|
I don't think the empty state should be centered in the middle of the page. In all our designs, it's positioned closer to the top so it sits better with the header above. 
|
Member
I think Separately, this does raise the need for more clarity on what |
Contributor
|
Dashboards and Analytics seem like a valid use case outside of DataViews. My feeling was that |
aduth
approved these changes
Mar 19, 2026
Member
aduth
left a comment
aduth
left a comment
There was a problem hiding this comment.
Based on what's discussed with how this is needed across both admin interface use-cases as well as DataViews, I think it makes sense to introduce this to the lower-level @wordpress/ui package, as proposed.
There are a couple minor things that need to be addressed per the review comments, but otherwise it looks good to me 👍
packages/ui/src/empty-state/icon.tsx
Outdated
| @@ -0,0 +1,24 @@ | |||
| import clsx from 'clsx'; | |||
| import { forwardRef } from '@wordpress/element'; | |||
| import { Icon as IconComponent } from '../icon'; | |||
Member
There was a problem hiding this comment.
We don't document common import conventions yet (we should), but typically I've seen this shadowing avoidance being implemented with underscore:
Suggested change
| import { Icon as IconComponent } from '../icon'; | |
| import { Icon as _Icon } from '../icon'; |
Granted, most of that existing usage is specifically aliasing BaseUI imports and not our own, but I think it could extend here as well.
| flex-direction: column; | ||
| align-items: center; | ||
| text-align: center; | ||
| gap: var( --wpds-dimension-gap-xs ); |
Member
There was a problem hiding this comment.
Per flagged errors, these need to be formatted without the spacing in the parentheses, per CSS guidelines.
use _Icon import convention, remove CSS var() spacing
Member
|
Regarding discussion of |
jameskoster
reviewed
Mar 20, 2026
| padding: var(--wpds-dimension-padding-surface-xs); | ||
| border: 1px solid var(--wpds-color-stroke-surface-neutral-weak); | ||
| border-radius: 50%; | ||
| background-color: var(--wpds-color-bg-surface-neutral); |
Contributor
There was a problem hiding this comment.
I just want to note that if #76548 is merged and EmptyState is rendered directly on the Page (as I assume is intended) then the icon background will effectively be invisible. We might want to consider using --wpds-color-bg-surface-neutral-weak instead, or drop the background altogether.
jameskoster
reviewed
Mar 20, 2026
| } | ||
|
|
||
| .description { | ||
| max-width: 350px; |
Contributor
There was a problem hiding this comment.
We could use a token here e.g. --wpds-dimension-surface-width-sm.
Contributor
There was a problem hiding this comment.
I wonder if this style should be applied to the container. I'm guessing we wouldn't want really wide titles.
jameskoster
reviewed
Mar 20, 2026
Comment on lines
+34
to
+35
| font-size: var(--wpds-font-size-lg); | ||
| line-height: var(--wpds-font-line-height-sm); |
avoids invisible icon background when rendered on Page surfaces after #76548
replaces hardcoded 350px on description with --wpds-dimension-surface-width-sm on container
delegates typography styles to Text variants instead of manual font-size/weight/line-height declarations
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
8 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What?
Adds a new
EmptyStatecompound component to the@wordpress/uipackage. This component displays placeholder content when a page or section has no data to show.Why?
EmptyState is a common UI pattern that provides visual feedback and guidance when content is absent. This component is being migrated from the design-system to Gutenberg as part of the ongoing UI component consolidation effort.
How?
The component follows the compound component pattern (like
Tooltip), providing flexible composition:Sub-components
EmptyState.Root- Container with centered flex layoutEmptyState.Visual- Generic visual container (for custom illustrations)EmptyState.Icon- Styled icon with circular border treatmentEmptyState.Title- Heading text (h2)EmptyState.Description- Supporting descriptive textEmptyState.Actions- Container for action buttons (responsive layout)Implementation details
@base-ui/reactprimitives (useRender,mergeProps)--wpds-dimension-gap-xs,--wpds-dimension-padding-surface-xs, etc.)@wordpress/uiconventions: no docblock comments for imports, CSS modules with layer orderingTesting