Dataviews: Allow DataViews empty state to be customized - #70867
Merged
Conversation
|
Size Change: +19 B (0%) Total Size: 1.91 MB
ℹ️ View Unchanged
|
p-jackson
force-pushed
the
add/customizable-dataviews-empty-state
branch
from
July 24, 2025 06:29
45e45d2 to
b10c412
Compare
p-jackson
force-pushed
the
add/customizable-dataviews-empty-state
branch
2 times, most recently
from
July 25, 2025 07:42
629cc46 to
801064a
Compare
p-jackson
commented
Jul 25, 2025
p-jackson
force-pushed
the
add/customizable-dataviews-empty-state
branch
from
July 25, 2025 08:07
b080ec4 to
4a6b208
Compare
p-jackson
marked this pull request as ready for review
July 25, 2025 08:07
|
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. |
p-jackson
added
[Type] Feature
Member
Author
|
@matt-west custom illustrations like this one, where the edges fade out, are a tricky design challenge. 
We want to have some consistent spacing between the illustration, copy, and buttons. However when the illustration fades out like this, in order for the elements to feel balanced, the gap between the copy and illustration has to be much tighter 🤔 |
9 tasks
simison
reviewed
Jul 25, 2025
simison
reviewed
Jul 25, 2025
| @@ -0,0 +1,23 @@ | |||
|
|
|||
| .dataviews-empty { | |||
| max-width: $modal-width-medium; | |||
Member
There was a problem hiding this comment.
A little surprising variable to use for inline (not modal) content width, but perhaps it's used more widely like so? 😅
Member
Author
There was a problem hiding this comment.
Yes I suppose it is a bit peculiar actually
But I guess what would be better would be some sort of $max-comfortable-reading-width variable. Maybe there's already something like that. However keep in mind it is used for constraining the illustration too.
Member
Author
There was a problem hiding this comment.
Apps will now be able to define their own empty state layouts, setting the max-width and copy style as they see fit :)
youknowriad
reviewed
Jul 25, 2025
| onChangeView={ setView } | ||
| actions={ actions } | ||
| defaultLayouts={ defaultLayouts } | ||
| empty={ { |
Contributor
There was a problem hiding this comment.
To be honest I'd rather have a custom component here. I'm not sure it's the role of the DataViews component to provide a structured API for this.
Contributor
There was a problem hiding this comment.
If we want to align the "empty" placeholder at the design system level, it feels like something that is independent of the DataViews and we could have a separate Empty component no?
Member
Author
There was a problem hiding this comment.
Developing the "empty" component independently of the DataViews sounds like a good suggestion. There's no intrinsic reason why such a component needs to be coupled to DataViews.
What does give me pause is allowing an arbitrary ReactElement to be passed in to the DataViews as a prop. Are we concerned that would encourage too many diverging designs? Another downside is we potentially have to support elements that could be using any sort of layout strategy. In order to support elements using absolute positioning will we get PRs adding position:relative wrappers inside DataViews? Do we need to gracefully handle the case where someone passes an element using float:right?
On the other hand, we already support "free composition" mode. And in that case we can't predict the layout strategies people are using either. So maybe we've already passed that rubicon.
Member
There was a problem hiding this comment.
While I can see the appetite for a more general purpose "empty" component set, I feel like in practice it'd end up being pretty specific to this context. For example, we have "empty placeholder" used on blocks, and it looks quite different to this one. At the same time, a nicer default on data views than just the empty text message could be worthwhile, but we should still allow folks to pass their own custom component regardless.
Contributor
Thanks for flagging! I’ll raise this with Jordan who is handling these illustrations. We can probably vary the styling to work around this. |
p-jackson
force-pushed
the
add/customizable-dataviews-empty-state
branch
from
July 31, 2025 08:19
4a6b208 to
e55e11a
Compare
Member
Author
|
Heads up @ciampo @youknowriad, I've reworked this PR. Enforcing a consistent empty-state layout is a good thing, but it should be designed and implemented at an app level. Note that I have added the |
|
Flaky tests detected in 2d15362. 🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/16643833258
|
youknowriad
reviewed
Jul 31, 2025
|
|
||
| - Field API: `isValid` is now an object that contains `required` and `custom` validation rules. Additionally, fields should now opt-in into being a "required" field by setting `isValid.required` to `true` (all fields of type `email` and `integer` were required by default). [#70901](https://github.com/WordPress/gutenberg/pull/70901) | ||
|
|
||
| ### Features |
Contributor
There was a problem hiding this comment.
There's now two "features" sections, we should combine them.
youknowriad
approved these changes
Jul 31, 2025
p-jackson
force-pushed
the
add/customizable-dataviews-empty-state
branch
from
August 3, 2025 21:13
2d15362 to
3c7f3c6
Compare
9 tasks
bph
changed the title
bph
added
[Type] Enhancement
simison
reviewed
Sep 3, 2025
| } ) } | ||
| > | ||
| <p>{ isLoading ? <Spinner /> : __( 'No results' ) }</p> | ||
| <p>{ isLoading ? <Spinner /> : empty }</p> |
Member
There was a problem hiding this comment.
@p-jackson, it's quite problematic to have <p> forced here, as one can't really place anything else except a single line of text and maybe links inside the p tag.
Examples like in the storybook won't produce semantic HTML:
Member
Author
There was a problem hiding this comment.
😮💨 That semantic error is a problem! I left the <p> there because I didn't want to break backwards compatibility of the DOM. But perhaps this deserves a breaking change? (someone would have to be targeting the p element with a CSS selector to cause a breakage, so I suppose it is a pretty soft breaking change as far as things go).
If we're going to rearrange things anyway, should the <Spinner> also be removed from the <p>? I'm thinking perhaps it should look like this:
{ isLoading ? <Spinner /> : empty }And the default empty element is changed to
empty = <p>{ __( 'No results' ) }</p>We would then need to add something to the changelog, saying that anyone passing plain text to the empty prop may now want to consider wrapping their empty text in a <p>.
Member
There was a problem hiding this comment.
Considering empty is a new prop, and DataViews isn't released yet as a package (so can be considered somewhat unstable still), I think breaking changes would be fine. I see minor breaking changes in each release recently.
3 tasks
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
6 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?
Part of #61442
Gives the
<DataViews>component the ability to display more contextual information when the view is empty.A user of the
<DataViews>component can either customize just the message, or provide aReactNodewhich allows for more general customizations to be made.Note: earlier versions of this PR were more prescriptive on the customizations that could be made
What can be shownA headingMore detailed descriptive textAn illustration<Button>sThis PR is backwards compatible.
If only theheadingproperty is customised, then it will render as regular paragraph-sized copy. Just like the existing "No results" empty state.This PR should make no visible changes to Gutenberg. Future PRs—and consumers of the
@wordpress/dataviewspackage—can follow up by making the customisations that are right for each specific situation.Hypothetical in situ custom error messages
A simple copy-only customisation.
Or a more elaborate custom behaviour.
Examples from storybook
Basic customization
Free composition
Why?
As is pointed out in #61442, there is often a lot of contextual help you can give the user when the data view is empty. Perhaps you can we can explain why there are no items. Or guide the user to create an item.
This supersedes #70637, which was another attempt where I allowed any arbitrary element to be used as the data view's empty state. This wouldn't provide enough consistency across all views. Better to do the hard work of aligning on design up front.This PR allows for generic customizations, rather than forcing a prescriptive form of empty message.
How?
I left some code comments about some of my rationale.
Notice that I have a single
headinganddescriptionand expect the calling code to change it depending on whether there is no data or the search couldn't find any results. We could ask the caller to provide a separatenoDataHeadingandnoSearchResultsHeadingand handle the logic internally. However I don't think this would be flexible enough. Perhaps we have only partially loaded the data, and we want to show a "load more" button. That means there are three different empty state cases, not two. The great thing about custom messages is that we can provide context for those messages that the data view can't know.Testing Instructions
To try the new empty states in storybook use
npm run storybook:dev.To test changes in a live
<Dataviews>component in Gutenberg, I've been using the pages list in the site editor. The code for that component is here:gutenberg/packages/edit-site/src/components/post-list/index.js
Line 412 in 76cb0ff
Testing Instructions for Keyboard
The action buttons are immediately after the dataview header in the tab order. When the dataview is in table mode, then they will be immediately after the column headers.
Another a11y note: the illustration should be purely illustrative since it has an empty
altattribute. The description should provide adequate detail explain what the user should do.