Playlist block #50664

carolinan · 2023-05-16T12:36:51Z

What?

Adds a playlist and it's inner playlist track block.

Closes #805

Why?

The playlist block has been requested since 2017. Without the block, a playlist can be added by using the classic block, but that is overly complicated.

How?

For this block, I started with one media type, audio, rather than trying to build it for both audio and video because it would increase the complexity.

I pictured that the playlist should work similarly to the "classic" WordPress playlist.
Meaning:

There would be only one audio element followed by an optional Tracklist with information like song title, artist, and track length.
Clicking on a track in the Tracklist should play that track.
When one track ends, the next track in the Tracklist should start.
The block options should match the playlist options in the Media Library.

Testing Instructions

Audio file for testing: https://wpthemetestdata.files.wordpress.com/2008/06/originaldixielandjazzbandwithalbernard-stlouisblues.mp3

Enable the experimental blocks option from the Gutenberg > Experiments plugin menu.
Upload a couple of audio files through the Media Library.
Edit the files in the Media Library and add title, artist and album to some files but not all.
Add a featured image to at least one file.

Insert the playlist block in the editor.

There should be a media placeholder from which you can open the media library and select audio files. Hold down Shift to select more than one file.
Confirm that all selected files are inserted in the block and that the first file is presented at the top of the block, above the tracklist.
Select the Edit button in the toolbar of the Playlist block . Upload or select a one or more files from the media library. Confirm that the files you choose replaces the current items in the block.
Please test the alignment options in the block toolbar.
Clicking on the play button of the audio element should be disabled.
Clicking on a playlist track should select the inner block and the block settings sidebar should show the options for the track, not the playlist itself.
Confirm that you can select one or more playlist track blocks and move them up and down using the move down, move up, or drag options.
Confirm that there are no issues/errors when deleting or duplicating a playlist track block.
Select a playlist track block and edit the title, album and artist by editing the text directly on the inner block in the canvas.
Select a playlist track block and edit the title, album and artist by editing the text using the options in the sidebar.
Select a playlist track block and delete all text contents. Confirm that placeholder texts are showing.
Select a playlist track block and upload an album cover image.
Replace the album cover image.
Remove the album cover image.
Try the sidebar options: Select the parent playlist block.

Show Tracklist -hides and shows the tracklist.
Show artists in Tracklist -hides and shows artists in the tracklist if the artist info is available.
Show number in Tracklist -hides and shows the number in the tracklist.
Show images -hides and shows the image for the track.
Order -change the order of the tracks.
In the Styles tab, change colors, spacing and borders.

View the front of the website.

Confirm that clicking the play button plays the track.
When a track ends, the next track plays until you reach the last track.
Clicking on a track in the tracklist switches the current track.
The current track is marked in bold in the tracklist.
Repeat this step with more than one playlist block placed on the same page.

Screen Readers

Description of the block:

The block has three different sections.
At the top, there is an image, for example, an album cover, which is set to decorative with an empty alt attribute.
Next to the image is information about the current track: Title, album, and artist.
Below is a native audio HTML element with the standard controls for playing, pausing, volume, etc.
Below the audio element is the tracklist.
It is a list with buttons inside. Each list item and button represents a track and the button text is the song title, artist, and the length of the track.
The currently selected track: The one that is at the top of the block, has aria-current=true.
Activating a button selects that track.

Instructions

(I have only tested these steps with VoiceOver on mac)

Enable the experimental blocks option from the Gutenberg > Experiments plugin menu.
Upload a couple of audio files through the Media Library.
Edit the files in the Media Library and add title, artist and album to some but not all.
Add a featured image to at least oner file.

Add a playlist block in the block editor.
Focus is moved to an upload button in the block's placeholder.
Instructions about uploading an audio file or selecting one from the media library are announced.
Pressing the right arrow key or the tab key moves the focus from the Upload button to the Media Library button. Each button opens its respective file selection flow.
Confirm that it is possible to select multiple files.
When clicking on the button with the text "Select", the modal for the Media Library is closed.

After adding the audio files, the focus is moved away from the block to the editor canvas and one has to navigate to the block again to select it. (I found this confusing, but learned that other media placeholders do the same)

Navigate to the block in the editor.
The block name is announced.
Pressing the down arrow key or the right arrow key moves focus to the audio element inside the playlist block.
The element type, the track title, the artist name, and the album name are announced if this information is available. Some tracks will only have a title. The same information that is announced is printed above the audio element, available to sighted users.

Pressing the spacebar or Enter key will play the track, and pressing the spacebar or Enter again will pause the track.
Let me know if playing the track in the editor should be disabled.

Pressing the down arrow key will move the focus to the button of the first track in the tracklist. The screen reader should announce the title, the band, the length of the track (if available), and the instructions "Select to play this track".

Pressing the down arrow key now selects the richText element for editing the song title.
Pressing the down arrow key now selects the second richText element, which is for editing the artist name.

Pressing the down arrow key again will select the next track in the tracklist, and so on, until you reach the last track.

Replacing or adding tracks

Because the tracks are inner blocks, there will be two block toolbars where you can edit tracks.
From the block toolbar of the inner block, you can replace the individual, single track.
From the block toolbar of the parent block, the playlist, you can add multiple new tracks at once.

Press Shift + Tab to open the block toolbar.
Use the arrow keys to navigate to the button named "Edit" or "Replace" respectively.
Activating the button opens a dropdown with two options: Open Media Library, and Upload.
Each option opens its respective file selection.
When the selection is complete, the screen reader announces that the media has been replaced.
(This is not accurate if you are adding a file, not replacing it, but I don't know if this can be solved?)
The focus is returned to the Edit button.

Block Sidebar

Both the playlist block and the inner track block has options in the block sidebar.

The Playlist has options both in the settings tab and styles tab.
Some of these options are visual, such as padding and margin and hiding the decorative image.
Optionally, test the first option in the settings tab, which is a toggle used to hide and show the tracklist:
With the block selected, press the tab key to move the focus to the sidebar.
Navigate to the block settings sidebar, past the Close button and the button that opens the Settings tab,
and the button that opens the Settings panel.
Find the checkbox option for "Show tracklist". Uncheck the checkbox.
Press the tab key repeatedly until you reach the "Skip to the selected block" button.
With the block selected, confirm that using the down arrow key does not move focus to the tracklist, since it has been turned off in the option.

The track has options in the settings tab.
With the block selected, press the tab key to move the focus to the sidebar.
Navigate to the block settings sidebar, past the Close button and the button that opens the Settings tab,
and the button that opens the Settings panel.
There will be three text input fields where you can update artist, album and title.
Below is an option for selecting an album cover image from the Media Library.

packages/block-library/src/playlist/edit.js

github-actions · 2024-01-08T11:39:59Z

This pull request has changed or added PHP files. Please confirm whether these changes need to be synced to WordPress Core, and therefore featured in the next release of WordPress.

If so, it is recommended to create a new Trac ticket and submit a pull request to the WordPress Core Github repository soon after this pull request is merged.

If you're unsure, you can always ask for help in the #core-editor channel in WordPress Slack.

Thank you! ❤️

View changed files

❔ lib/blocks.php
❔ lib/experimental/editor-settings.php
❔ lib/experiments-page.php

Use children instead, as the props on the tag itself broke the border styles.

…que id as a prefix

carolinan · 2025-07-06T14:06:09Z

I had to change how the block uses the interactivity API global state.
When a playlist block was duplicated, each track's unique id was no longer truly unique, and this caused a problem with the album cover image.
The image that was used on the playlist block that was placed last in the content, was also used in all other playlist blocks
(as long as the "show image" option was enabled).

It still uses the state, but, how do I say this in plain English,.. each playlist is isolated because the track data is nested one level deeper under a playlist id.

MaggieCabrera

This is testing really nicely for me, since it's under an experiment I think it's fair to bring it in and we can iterate if we feel like we need to

scruffian · 2025-09-10T13:53:29Z

packages/block-library/src/playlist-track/edit.js

+				<MediaReplaceFlow
+					name={ __( 'Replace' ) }
+					onSelect={ onSelectTrack }
+					accept="audio/*"


What's the difference between accept and allowedTypes?

MaggieCabrera · 2025-09-10T13:58:54Z

I might have jumped the gun :D I get an error when trying to change the sort order and it doesn't work: Uncaught TypeError: can't access property "localeCompare", b.attributes.uniqueId is undefined. This doesn't happen consistently, I added a new song and then it worked!

scruffian · 2025-09-10T14:03:14Z

I'm not sure I fully see the value of the sort control:

Since I can reorder the inner blocks, I'm not sure when this would be useful....

MaggieCabrera · 2025-09-10T14:04:04Z

Since I can reorder the inner blocks, I'm not sure when this would be useful....

If the numbers update when manually sorting I agree with this

scruffian · 2025-09-10T14:07:58Z

When the block saves it outputs an <ol> in the markup - I wonder if it would be better to omit the <ol>, as it doesn't add much useful semantic information, and it will make it more complex to update the markup in future.

mikachan · 2025-09-10T14:05:17Z

packages/block-library/src/playlist/edit.js

+
+	// Ensure that each inner block has a unique ID,
+	// even if a track is duplicated.
+	useEffect( () => {


I think this could be fixed in a follow-up, but it looks like this useEffect is running on every render. We could try memoising the unique IDs to avoid unnecessary re-renders.

Something like:

const uniqueIds = useMemo( () => { return innerBlockTracks.map( ( block ) => block.attributes.uniqueId ); }, [ innerBlockTracks ] );

And then add uniqueIds as a dependency to the useEffect.

I have tried many different alternatives but was not able to get it working :(

I think it's OK to come back to this later, don't let it block this PR!

scruffian

Thanks for working on this, I love it ❤️ 🎧 . I think we should bring this in and keep iterating.

getdave

Couple of things to consider prior to merge.

getdave · 2025-09-10T14:12:38Z

packages/block-library/src/playlist-track/index.php

+		sprintf(
+			/* translators: %s: track length in minutes:seconds */
+			'<span class="screen-reader-text">' . esc_html__( 'Length:' ) . ' </span>%s',
+			$length


Suggested change

$length

esc_html( $length )

getdave · 2025-09-10T14:19:08Z

packages/block-library/src/playlist/index.php

+				$tracks_data[ $unique_id ] = array(
+					'url'       => $url,
+					'title'     => $title,
+					'artist'    => $artist,
+					'album'     => $album,
+					'image'     => $image,
+					'ariaLabel' => $aria_label,
+				);


These values may need escaping.

For example ariaLabel is used in data-wp-bind--aria-label so will need esc_attr.

carolinan · 2025-09-11T04:00:40Z

Thank you all for the reviews ❤️

The ascending/descending sorting option, if I remember correctly, was included to match the ordering option in the classic playlist in the media library. I don't have strong preference for or against it.
Anyone who has the availability please feel free to continue. I might be able to catch up with the notes on Saturday.

carolinan · 2025-09-11T04:05:17Z

I'd be OK with it not being reviewed for accessibility while it stays experimental. But it needs to be tested before removing that flag.

t-hamano

I've only seen the final code, but I'll comment on some points that I noticed. I apologize if I'm mistaken.

Also, I think it would be better to merge trunk into this branch again before shipping this PR. For example, this if statement already exists in trunk, so this diff is weird.

t-hamano · 2025-09-11T06:38:49Z

lib/blocks.php

+				'playlist.php'                     => 'core/playlist',
+				'playlist-track.php'               => 'core/playlist-track',


Let's put them in strict alphabetical order (directly under patterns.php).

t-hamano · 2025-09-11T06:42:23Z

packages/block-library/src/playlist/save.js

+				className={
+					'wp-block-playlist__tracklist' +
+					( ! showTracklist
+						? ' wp-block-playlist__tracklist-is-hidden'
+						: '' ) +
+					( ! showArtists
+						? ' wp-block-playlist__tracklist-artist-is-hidden'
+						: '' )
+				}


Let's avoid concatenating class names as strings, as this can introduce unintended spaces.

Suggested change

className={

'wp-block-playlist__tracklist' +

( ! showTracklist

? ' wp-block-playlist__tracklist-is-hidden'

: '' ) +

( ! showArtists

? ' wp-block-playlist__tracklist-artist-is-hidden'

: '' )

}

className={ clsx( 'wp-block-playlist__tracklist', {

'wp-block-playlist__tracklist-is-hidden': ! showTracklist,

'wp-block-playlist__tracklist-artist-is-hidden':

! showArtists,

} ) }

t-hamano · 2025-09-11T06:44:56Z

packages/block-library/src/playlist-track/edit.js

+/**
+ * External dependencies
+ */
+import { v4 as uuid } from 'uuid';


Is there a reason why you didn't use useInstanceId hook?

t-hamano · 2025-09-11T06:46:45Z

packages/block-library/src/playlist-track/edit.js

+				/>
+			</BlockControls>
+			<InspectorControls>
+				<PanelBody title={ __( 'Settings' ) }>


Not a blocker, but it would be great to see this refactored to use ToolsPanel in the future. See #67813

Yeah, all blocks should use ToolsPanel AFAIK.

t-hamano · 2025-09-11T06:47:53Z

packages/block-library/src/playlist-track/edit.js

+						onChange={ ( value ) => {
+							setAttributes( { title: value } );
+						} }
+						keepPlaceholderOnFocus


There is no such prop in the RichText component.

t-hamano · 2025-09-11T06:51:26Z

packages/block-library/src/playlist-track/edit.js

+						} }
+					/>
+					<MediaUploadCheck>
+						<div className="editor-video-poster-control">


Not a blocker: There is a reusable PosterImage component for poster images that we might be able to use.

t-hamano · 2025-09-11T06:54:24Z

packages/block-library/src/playlist-track/edit.js

+					data-playlist-track-url={ src }
+					data-playlist-track-title={ stripHTML( title ) }
+					data-playlist-track-artist={ stripHTML( artist ) }
+					data-playlist-track-album={ stripHTML( album ) }
+					data-playlist-track-image-src={ image ?? null }
+					data-wp-context={ JSON.stringify( { uniqueId } ) }


Why are these attributes needed?

t-hamano · 2025-09-11T06:57:25Z

packages/block-library/src/playlist-track/index.php

+
+	$wrapper_attributes = get_block_wrapper_attributes();
+
+	$unique_id = isset( $attributes['uniqueId'] ) ? $attributes['uniqueId'] : wp_generate_uuid4();


wp_unique_id might be more appropriate

t-hamano · 2025-09-11T07:01:31Z

packages/block-library/src/playlist-track/index.php

+		$html .= '<span class="wp-block-playlist-track__length">' .
+		sprintf(
+			/* translators: %s: track length in minutes:seconds */
+			'<span class="screen-reader-text">' . esc_html__( 'Length:' ) . ' </span>%s',


Suggested change

'<span class="screen-reader-text">' . esc_html__( 'Length:' ) . ' </span>%s',

'<span class="screen-reader-text">Length:</span>%s',

The text and placeholder order may vary depending on the locale.

t-hamano · 2025-09-11T07:07:25Z

packages/block-library/src/playlist/edit.js

+							{ label: __( 'Descending' ), value: 'DESC' },
+							{ label: __( 'Ascending' ), value: 'ASC' },


Suggested change

{ label: __( 'Descending' ), value: 'DESC' },

{ label: __( 'Ascending' ), value: 'ASC' },

{ label: __( 'Descending' ), value: 'desc' },

{ label: __( 'Ascending' ), value: 'asc' },

In general, I think it's best to use lowercase values.

MaggieCabrera · 2025-09-11T09:25:56Z

Thank you all for the reviews ❤️

Thank you for all your work here

The ascending/descending sorting option, if I remember correctly, was included to match the ordering option in the classic playlist in the media library. I don't have strong preference for or against it. Anyone who has the availability please feel free to continue. I might be able to catch up with the notes on Saturday.

Yeah, makes sense if we didn't have visual editing for it back then, but less so when just dragging things around will achieve the same result

carolinan · 2025-09-11T11:02:23Z

Unless you have 100+ items... but then you probably want to use a more custom block anyway.

carolinan added 10 commits May 11, 2023 11:08

Basic playlist block

8b44789

try to make some accessibility improvements

4198e21

Park the PHP file until work can continue

ac17285

Update index.php

1fcbf71

Update index.php, try to solve merge conflicts

8aed3d3

Remove the style variation

14e1fa5

Remove the unused save, add escaping, update css

92a3c65

Update edit.js

59bb48f

Update edit.js

4ba31d9

Update edit.js

1e94427

carolinan added New Block Suggestion for a new block [Type] Experimental Experimental feature or API. labels May 16, 2023

Merge branch 'trunk' into try/playlist2

00d6970

carolinan requested a review from antpb May 16, 2023 12:42

This comment was marked as outdated.

Sign in to view

carolinan added 5 commits May 17, 2023 11:51

fix CS issues

ca834be

Fix two issues with the upload option.

cce2cc5

Disable uploading and selecting multiple files in the replacement flow.

54cc037

Update the placeholder instructions

381650a

Merge branch 'trunk' into try/playlist2

ff810d2

carolinan commented May 21, 2023

View reviewed changes

packages/block-library/src/playlist/edit.js Outdated Show resolved Hide resolved

carolinan commented May 21, 2023

View reviewed changes

packages/block-library/src/playlist/edit.js Outdated Show resolved Hide resolved

Correct a translators comment.

dab0e24

This comment was marked as outdated.

Sign in to view

Hide tracklist options if the tracklist itself is toggled off

04a8368

This comment was marked as resolved.

Sign in to view

carolinan added 2 commits July 11, 2023 10:50

Merge branch 'trunk' into try/playlist2

19fc308

Merge branch 'trunk' into try/playlist2

7358614

Merge branch 'trunk' into try/playlist2

8bb139e

carolinan added 12 commits July 4, 2025 14:26

remove test code

675f87c

Ensure that each inner block has a unique ID even when duplicated

5246288

Merge branch 'trunk' into try/playlist2

df69608

Don't include the media placeholder in the tracklist

17313df

Fix the options to hide the tracklist and artist name

d895e2a

Tracklist: replace innerBlocksProps with innerBlocksProps.children

cd4f23f

Use children instead, as the props on the tag itself broke the border styles.

Re-add the early return.

53a65f9

Fix the CSS for hidden tracklist

a829b43

Update style.scss

49c7486

Update since to 6..9.0

69a0508

Playlist track: correct the data-wp-context in the editor

095e39d

Try to isolate each playlist block in the global state by using a uni…

e86aad2

…que id as a prefix

carolinan added 2 commits July 6, 2025 16:22

Merge branch 'trunk' into try/playlist2

b5e43ee

Merge branch 'trunk' into try/playlist2

366c531

MaggieCabrera approved these changes Sep 10, 2025

View reviewed changes

scruffian reviewed Sep 10, 2025

View reviewed changes

mikachan reviewed Sep 10, 2025

View reviewed changes

scruffian approved these changes Sep 10, 2025

View reviewed changes

getdave reviewed Sep 10, 2025

View reviewed changes

t-hamano reviewed Sep 11, 2025

View reviewed changes

t-hamano mentioned this pull request Oct 1, 2025

New block: Playlist #71992

Closed

3 tasks

		'playlist.php' => 'core/playlist',
		'playlist-track.php' => 'core/playlist-track',


		$wrapper_attributes = get_block_wrapper_attributes();

		$unique_id = isset( $attributes['uniqueId'] ) ? $attributes['uniqueId'] : wp_generate_uuid4();

	'<span class="screen-reader-text">' . esc_html__( 'Length:' ) . ' </span>%s',
	'<span class="screen-reader-text">Length:</span>%s',

		{ label: __( 'Descending' ), value: 'DESC' },
		{ label: __( 'Ascending' ), value: 'ASC' },

Playlist block #50664

Are you sure you want to change the base?

Playlist block #50664

Uh oh!

Conversation

carolinan commented May 16, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What?

Why?

How?

Testing Instructions

Screen Readers

Description of the block:

Instructions

Replacing or adding tracks

Block Sidebar

Uh oh!

This comment was marked as outdated.

Uh oh!

Uh oh!

This comment was marked as outdated.

This comment was marked as resolved.

github-actions bot commented Jan 8, 2024

Uh oh!

carolinan commented Jul 6, 2025

Uh oh!

MaggieCabrera left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

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

Uh oh!

Uh oh!

scruffian commented Sep 10, 2025

Uh oh!

MaggieCabrera commented Sep 10, 2025

Uh oh!

scruffian commented Sep 10, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

scruffian left a comment

Choose a reason for hiding this comment

Uh oh!

getdave left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

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

Uh oh!

Uh oh!

carolinan commented Sep 11, 2025

Uh oh!

t-hamano left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

carolinan commented May 16, 2023 •

edited

Loading

MaggieCabrera commented Sep 10, 2025 •

edited

Loading

carolinan commented Sep 11, 2025 •

edited

Loading