New Block: Description List by ellatrix · Pull Request #20760 · WordPress/gutenberg

ellatrix · 2020-03-10T11:30:43Z

Description

https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dl

This is a block that I think would have been more difficult to implement without the use of light blocks. With light blocks, we're able to use proper semantic tags in the editor, which also allow it to be styled more easily.

To do: it might be could to handle enter/delete from rich text.

How has this been tested?

Screenshots

Types of changes

Checklist:

My code is tested.
My code follows the WordPress code style.
My code follows the accessibility standards.
My code has proper inline documentation.
I've included developer documentation if appropriate.
I've updated all React Native files affected by any refactorings/renamings in this PR.

Soean · 2020-03-10T11:43:39Z

Fixes #4880

mcsf

Definitely cool to see how neatly we can build this now.

Now, can we make this more ergonomic? Suggestions:

dd: Enter twice to start a new dt (not too different from
dt: Space (like List blocks) to convert to dd
dd: (not sure about this one) Backspace to to convert to dt
Add transforms between those two types
Because DLs are visually so clean, I wonder if we need visual cues to let the user know that they are starting a new dt or dd — but what?

ellatrix · 2020-03-10T18:01:52Z

Yes, I left that as a to do :D

To do: it might be could to handle enter/delete from rich text.

I think we should also take into account that you can have multiple dt elements (terms) and multiple dd elements (details). In other words, you could have multiple entries explaining a term, and you can have multiple terms for one explanation. See https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dl#Multiple_terms_single_description.

Maybe we could have Enter once create a block of the same type, and Enter twice create a block of the other type. This will require more context of surrounding blocks though.

mcsf · 2020-03-10T18:38:11Z

I think we should also take into account that you can have multiple dt elements (terms) and multiple dd elements (details).

Good reminder. Additionally, this to me reinforces the need for us to somehow address: "Because DLs are visually so clean, I wonder if we need visual cues to let the user know that they are starting a new dt or dd"

Maybe we could have Enter once create a block of the same type, and Enter twice create a block of the other type. This will require more context of surrounding blocks though.

Might work, yeah.

ZebulanStanphill · 2020-04-03T21:26:42Z

+	keywords: [ __( 'list' ), __( 'definitions' ), __( 'terms' ) ],
+	category: 'layout',
+	supports: {
+		className: false,


Why is this set to false?

For consistency, I think we should add color controls to this block if we add them to the List block.

ZebulanStanphill · 2020-04-03T21:27:43Z

+export const settings = {
+	title: __( 'Description List' ),
+	description: __( 'List groups of terms and descriptions.' ),
+	keywords: [ __( 'list' ), __( 'definitions' ), __( 'terms' ) ],


I don't think list is a necessary keyword when the title already includes that word. Maybe glossary would be a better keyword to use here?

ZebulanStanphill · 2020-04-03T21:28:45Z

+
+export const settings = {
+	title: __( 'Description List' ),
+	description: __( 'List groups of terms and descriptions.' ),


Suggested change

description: __( 'List groups of terms and descriptions.' ),

description: __( 'List of terms and their descriptions.' ),

ZebulanStanphill · 2020-04-03T21:34:11Z

+	},
+	edit,
+	save,
+	attributes: {


This, the name, and the category should be moved to a block.json. (Same with other blocks being added in this PR.)

paaljoachim · 2021-01-22T12:01:04Z

Quite some time has passed since there was any movement here.
What can do to help move this PR forward?

peroyomas · 2021-04-22T04:57:19Z

Currently both the WHATWG and the W3C HTML5 standards support grouping dt and dd tags using the div element (link to the issue were it was first discussed), which is useful on several cases where a single concept uses more than one dt or dd tag and stuff like CSS and semantics becomes tricky. I think that would be nice to automatically wrap groups of x number of dt followed by x number of dd in div tags, even if in a list the dt and dd elements aren't directly followed by dt or dd slibings respectively.

ellatrix · 2021-09-02T12:17:54Z

Wrapping in divs is tricky, because then we somehow need to ensure that inside that div dt elements come first and the dd elements follow. If these are mixed, then there's no point to group them.

ghost · 2023-03-05T21:29:11Z

@ellatrix Are you still working on this? And could you summarize anything that's left to be done before this can be merged?

hans2103 · 2023-12-20T09:19:14Z

Quite some time has passed since there was any movement here.
What can do to help move this PR forward?

Link to the first website ever
https://info.cern.ch/hypertext/WWW/TheProject.html
See source code... even a description list over there!

hans2103

tested successfully

@youknowriad
@talldan
@Soean
@ajitbohra
@jorgefilipecosta

you are assigned as reviewer. Please take action on it and test this PR. We're missing the Description List

hacknug · 2024-12-05T09:58:57Z

@hans2103 just use a plugin. It is obvious they don't see any value on adding this block. Issues were opened during the alpha or beta stages of Gutenberg around 2018 iirc and people have been waiting ever since. I don't even work with WordPress anymore after seeing all of this lol

github-actions · 2024-12-05T09:59:13Z

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 props-bot label.

Unlinked Accounts

The following contributors have not linked their GitHub and WordPress.org accounts: @hans2103, @ahaubold, @JanBolmeson, @acidrums4, @sarahmonster, @lassemt, @DietteJanssen, @hartl.

Contributors, please read how to link your accounts to ensure your work is properly credited in WordPress releases.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Unlinked contributors: hans2103, ahaubold, JanBolmeson, acidrums4, sarahmonster, lassemt, DietteJanssen, hartl.

Co-authored-by: ellatrix <ellatrix@git.wordpress.org>
Co-authored-by: mcsf <mcsf@git.wordpress.org>
Co-authored-by: ZebulanStanphill <zebulan@git.wordpress.org>
Co-authored-by: Soean <soean@git.wordpress.org>
Co-authored-by: paaljoachim <paaljoachim@git.wordpress.org>
Co-authored-by: peroyomas <atoon@git.wordpress.org>
Co-authored-by: hacknug <hack_nug@git.wordpress.org>
Co-authored-by: chubes4 <extrachill@git.wordpress.org>
Co-authored-by: SteveRyan-ASU <tfserwin@git.wordpress.org>
Co-authored-by: bobbingwide <bobbingwide@git.wordpress.org>
Co-authored-by: strarsis <strarsis@git.wordpress.org>
Co-authored-by: benoitchantre <benoitchantre@git.wordpress.org>

At least one ghost was discovered. ghosts represent deleted GitHub user accounts.

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

ahaubold · 2025-05-17T09:40:36Z

Hi everyone,

I’ve been looking for a way to use a definition list in Gutenberg and came across this ticket – it looks like a promising and well-considered proposal.

Since

support is quite valuable for structured content (e.g., glossaries, term lists, accessibility use cases), I was wondering if there are any plans to pick this up again or move it forward.

I understand that priorities shift over time, but I’d love to see this become part of Gutenberg if possible. Is there anything that might help to revive the discussion around this block?

Thanks again to everyone involved for your effort!

github-actions · 2026-01-28T10:52:05Z

Warning: Type of PR label mismatch

To merge this PR, it requires exactly 1 label indicating the type of PR. Other labels are optional and not being checked here.

Required label: Any label starting with [Type].
Labels found: New Block.

Read more about Type labels in Gutenberg. Don't worry if you don't have the required permissions to add labels; the PR reviewer should be able to help with the task.

chubes4 · 2026-05-07T02:22:47Z

Let's land this!

SteveRyan-ASU · 2026-09-02T05:28:55Z

For anyone following this earlier implementation, a current Description List block proposal is now open in #81728.

The newer PR builds on the ideas explored here while updating the implementation for current Gutenberg APIs. It uses separate Description List, Description Term, and Description Detail blocks; preserves flexible multiple-term and multiple-description sequences; and includes toolbar and Tab/Shift+Tab transforms between term and detail blocks.

It is currently up to date with trunk, and all automated checks are passing. Review and feedback would be very welcome on #81728.

New Block: Description List

a6df07d

ellatrix requested a review from mcsf March 10, 2020 11:30

ellatrix requested review from Soean, ajitbohra, jorgefilipecosta, talldan and youknowriad as code owners March 10, 2020 11:30

Soean added the New Block Suggestion for a new block label Mar 10, 2020

mcsf reviewed Mar 10, 2020

View reviewed changes

ZebulanStanphill reviewed Apr 3, 2020

View reviewed changes

ellatrix mentioned this pull request Aug 20, 2020

Block for description list #4880

Open

Base automatically changed from master to trunk March 1, 2021 15:43

ghost assigned ellatrix Mar 5, 2023

hans2103 approved these changes Dec 5, 2024

View reviewed changes

benoitchantre mentioned this pull request Aug 17, 2025

New Block additions for the Block Library #71026

Open

9 of 14 tasks

gutenbergplugin requested a review from fabiankaegy as a code owner January 28, 2026 10:51

chubes4 mentioned this pull request Jul 26, 2026

Preserve direct HTML description lists through a companion block Automattic/blocks-engine#694

Closed

This was referenced Jul 26, 2026

Preserve direct HTML description lists through a companion block Automattic/blocks-engine#695

Merged

Materialize typed companion blocks Automattic/static-site-importer#729

Merged

SteveRyan-ASU mentioned this pull request Aug 17, 2026

Block Library: Add Description List block #81728

Open

ellatrix closed this Sep 3, 2026

youknowriad deleted the try/description-list-block branch September 4, 2026 07:55

	description: __( 'List groups of terms and descriptions.' ),
	description: __( 'List of terms and their descriptions.' ),

Conversation

ellatrix commented Mar 10, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

How has this been tested?

Screenshots

Types of changes

Checklist:

Uh oh!

Soean commented Mar 10, 2020

Uh oh!

mcsf left a comment

Choose a reason for hiding this comment

Uh oh!

ellatrix commented Mar 10, 2020

Uh oh!

mcsf commented Mar 10, 2020

Uh oh!

ZebulanStanphill Apr 3, 2020

Choose a reason for hiding this comment

Uh oh!

ZebulanStanphill Apr 3, 2020

Choose a reason for hiding this comment

Uh oh!

ZebulanStanphill Apr 3, 2020

Choose a reason for hiding this comment

Uh oh!

ZebulanStanphill Apr 3, 2020

Choose a reason for hiding this comment

Uh oh!

paaljoachim commented Jan 22, 2021

Uh oh!

peroyomas commented Apr 22, 2021

Uh oh!

ellatrix commented Sep 2, 2021

Uh oh!

ghost commented Mar 5, 2023

Uh oh!

hans2103 commented Dec 20, 2023

Uh oh!

hans2103 left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

hacknug commented Dec 5, 2024

Uh oh!

github-actions Bot commented Dec 5, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Unlinked Accounts

Uh oh!

ahaubold commented May 17, 2025

Uh oh!

github-actions Bot commented Jan 28, 2026

Uh oh!

chubes4 commented May 7, 2026

Uh oh!

SteveRyan-ASU commented Sep 2, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

11 participants

ellatrix commented Mar 10, 2020 •

edited

Loading

hans2103 left a comment •

edited

Loading

github-actions Bot commented Dec 5, 2024 •

edited

Loading