Repository navigation
Block for description list #4880
Description
Issue Overview
Description lists (<dl>) are useful to implement a glossary or to display metadata as a list of key-value pairs. I think it would be interesting to add them as block to offer editors the right markup for their glossaries, product/services specifications, etc. directly in the post content.
This tag seems underused, but I see a lot of use cases. Why not to making it more visible, easy to use and in the same time to promote the use of the right markup?
Possible Solution
As suggested by @aduth in the Slack channel, this block could be seen as a variation of the "List" block.
Poll
Do you use this tag frequently? (if not: why)
Activity
bobbingwide commentedon Feb 6, 2018
I have a shortcode called [bw_csv] which supports user selection of the type of list: ordered, unordered, definition and - the original reason for the shortcode - table - created from comma separated data. It doesn't work in Gutenberg since it relies on new lines not being stripped. see #4456. Eventually I would like to be able to replace my shortcode with a block of easy to enter content which formats as required. The first thing that's required is a freeform block where Gutenberg respects new lines.
I would support a block that allowed selection of the list type and an easy way to choose how it's displayed. Whether or not you can easily extend the List block type is debatable.
PS. I've been calling them definition lists, rather than description lists, for many years.
Today was the first time I realised you could have multiple dt's for a dd.
JanBolmeson commentedon Aug 17, 2018
@sarahmonster - any specific reason why you removed it from the great block review? I think this is an important list I use all the time. :-)
acidrums4 commentedon Aug 17, 2018
I just happened to stumble upon this, while needing to add some "description lists" on a page. Seems strange to me that there's no "description list" block within Gutenberg. I really thought people used to use
<dl>tags.sarahmonster commentedon Aug 20, 2018
Hi @JanBolmeson, we're only able to review blocks that have an implementation (so they're either merged into master or have an outstanding pull request.) Doesn't mean that the block is off the table, just that we can't review it until there's a pull request. 🙂
lassemt commentedon Dec 6, 2018
I have created a plugin that can be used as a temporary solution until description list is implemented in core: https://github.com/lassemt/wp-block-description-list
DietteJanssen commentedon Dec 12, 2018
this is great @lassemt, thank you. i have been searching high and low - would you ( or could someone ) explain how to add this custom block into the list of allowed blocks of the core/media-text block?
acidrums4 commentedon Dec 12, 2018
@DietteJanssen Do you mean for using @lassemt block? If that's the case, just clone that repo under your wp-content/plugins folder
DietteJanssen commentedon Dec 13, 2018
@acidrums4 no - i'm talking about making it accessible from the core block "media & text". by default the core/media-text block only allows the following inner blocks: 'core/button', 'core/paragraph', 'core/heading', 'core/list'. the gutenberg handbook implies that blocks can be extended and i've been able to add to extend other core blocks, but i'm having trouble figuring out how to achieve this particular case scenario.
ideally, i would like to have the "description list" as a third option in the core/list block which would then also be available within the core/media-text (or any other block that allows the core/list block as an innerblock). but i'll settle for just being able to add a custom block to the list of allowed inner blocks within the core/media-text block, since it is likely i'll need this as an option at some point too.
lassemt commentedon Dec 14, 2018
@DietteJanssen sorry for the late answer, it's a bit busy before christmas🎄
Looking at the Media & Text block I can see in the code what inner blocks that are allowed for the Media & Text block. With that said I'm currently working on improving my block (lassemt/wp-block-description-list#2) to follow the official html spec. According to the spec
<dd>is permitted to use flow content which means it is allowed to use images, headlines, etc. inside the<dd>tag. So having this inside a Media & Text block might be a bit weird (depends on usage of course). A work around that might work is to use columns and add image to the first column and the description list in the other. I will let you know when I figure out how to extend "Allowed blocks" in media & text.Regarding implementing a description list into the existing core/list block was my original plan and something I started to pursue. What made hard for me to implement in a clean way is that RichText dont support
<dt>and<dd>for multilines. I tried to workaround this by using RichText's onSplit function, but this function was marked as unstable (#10761) while I was working on it. So I ended up with the solution in my custom description list block.I hope this makes sense 😊
Thoughts on implementing a description list in core
To make it work in the existing core/list, RichText needs some altering to support
<dt>and<dd>. It will also need a way to convert between these tags "per line" in multiline since a<dt>can be followed by multiple<dt>or<dd>elements..Something that should be also considered before implementation, is if content-creators use the
<dd>tag in the same way as a<li>tag in WordPress where it only contain text. Or should a<dd>tag be able to contain images, headlines, paragraphs, etc..DietteJanssen commentedon Dec 14, 2018
@lassemt wonderful thank you for such an in-depth reply. my plan of coding attack is very similar to what you've already been through and i appreciate the insight. i had previously implemented your suggested workaround, as was my backup plan.
i agree and think gutenberg developers should implement a text only definition list (to be used with the core/list). a separate, independent
<dd>block to be used with media, although the use case scenarios for that i would imagine are low enough, would maybe be better suited to use as an example within gutenberg docs for creating a custom block that accepts inner blocks.please do update me if you (or anyone else) stumble across a solution extending the "allowed blocks". i've had to develop custom call-to-action links (buttons which open a new window, & styled links ) for my client and have been forced to use the work around solution you described above, which isn't ideal, but i suppose that's probably better suited for a different discussion topic.
strarsis commentedon Mar 1, 2020
It would be great if a Definition List block is added to Gutenberg core!
Edit: The block from the Simple Definition List Blocks plugin works fine so far.
ellatrix commentedon Aug 20, 2020
Yes, started this in #20760. Would be good to finish I guess. Feedback there welcome.
hartl commentedon Apr 17, 2026
With LLMs in mind, having description lists is pretty much a must-have for a next-gen CMS. Hope this gets added soon!
chubes4 commentedon Aug 1, 2026
This gap recently surfaced in a generic HTML-to-block transformation pipeline. Without a core description-list representation, preserving an imported
<dl>as editable semantic content required eithercore/htmlor a custom block.We implemented the latter as a generated
blocks-engine/description-listcompanion in Automattic/blocks-engine#738. The implementation is here:DescriptionListBlockGenerator.php.The source corpus reinforced some of the structural requirements already discussed in this issue and #20760:
<dl>,<dt>, and<dd>output with editable RichText fields.dtfollowed by onedd.<div>grouping around term/description groups, as permitted by the HTML standard.This works as a downstream compatibility layer, including for grouped metadata rows in a multi-page visual-parity fixture, but it adds a custom-block dependency solely because no core block can represent the source semantics. A core implementation would let importers produce portable core-only content and retire this workaround.