Introducing the Gallery widget

In the last major releasemajor release A release, identified by the first two numbers (3.6), which is the focus of a full release cycle and feature development. WordPress uses decimaling count for major release versions, so 2.8, 2.9, 3.0, and 3.1 are sequential and comparable in scope. we introduced Media Widgets for Images, Video, and Audio. Per that dev notedev note Each important change in WordPress Core is documented in a developers note, (usually called dev note). Good dev notes generally include: a description of the change; the decision that led to this change a description of how developers are supposed to work with that change. Dev notes are published on Make/Core blog during the beta phase of WordPress release cycle. Publishing dev notes is particularly important when plugin/theme authors and WordPress developers need to be aware of those changes.In general, all dev notes are compiled into a Field Guide at the beginning of the release candidate phase.:

WordPress 4.8 includes media widgets (#32417) for not only images (#39993) but also video (#39994) and audio (#39995), on top of an extensibleExtensible This is the ability to add additional functionality to the code. Plugins extend the WordPress core software. base for introducing additional media widgets in the future, such as for galleries and playlists.

Now in the upcoming 4.9 releaseRelease A release is the distribution of the final version of an application. A software release may be either public or private and generally constitutes the initial or new generation of a new or upgraded application. A release is preceded by the distribution of alpha and then beta versions of the software. this Gallery widgetWidget A WordPress Widget is a small block that performs a specific function. You can add these widgets in sidebars also known as widget-ready areas on your web page. WordPress widgets were originally created to provide a simple and easy-to-use way of giving design and structure control of the WordPress theme to the user. (#41914) has just landed in trunktrunk A directory in Subversion containing the latest development code in preparation for the next major release cycle. If you are running "trunk", then you are on the latest revision. in [41590]. Just as users can add galleries to their post content they too can add galleries to their sidebars. The media widgets are being developed with GutenbergGutenberg The Gutenberg project is the new Editor Interface for WordPress. The editor improves the process and experience of creating new content, making writing rich content much simpler. It uses ‘blocks’ to add richness rather than shortcodes, custom HTML etc. in mind, as widgets are essentially proto-blocks. Gutenberg has ported the Categories and Recent Posts widgets as dynamic blocks so that users can add to their posts what was formerly restricted to sidebars. In the same way, the media widgets are allowing for content that was formerly restricted to post content to also be available for addition to widget areas. As Gutenberg matures, widgets are planned to eventually transition over to use blocks, and the widgets for images, video, audio, and galleries will be able to be migrated over at that time. In the mean time, the user should not have to know there is any difference between post content and widget areas. Once the migrationMigration Moving the code, database and media files for a website site from one server to another. Most typically done when changing hosting companies. from widgets to blocks is complete, users shouldn’t actually perceive any fundamental change in this regard.

Here are four screenshots that show how the Gallery widget is created and updated:


You’ll note that the widget re-uses the same media modals that a user is familiar with when adding and editing galleries in the post editor.

Code Reference

PHPPHP The web scripting language in which WordPress is primarily architected. WordPress requires PHP 5.6.20wp-includes/widgets/class-wp-widget-media-gallery.php
JSJS JavaScript, a web scripting language typically executed in the browser. Often used for advanced user interfaces and behaviors.: wp-admin/js/widgets/media-gallery-widget.js

Field Type Default Description
title string "" Title for the widget
ids array [] Attachment IDs
columns integer 3 Columns
size string "thumbnail" Size
link_type string "none" Link To
orderby_random boolean false Order by random

There is also a widget_media_gallery_instance_schema filterFilter Filters are one of the two types of Hooks They provide a way for functions to modify data of other functions. They are the counterpart to Actions. Unlike Actions, filters are meant to work in an isolated manner, and should never have side effects such as affecting global variables and output. which can be used to add additional properties, such as a type for Jetpack’s Tiled Galleries. See #42285.

Theme Styling Updates

As with the previously-introduced media widgets, some themes will need to be updated to ensure the proper styling is applied to galleries that appear in the widget area context, since previously galleries would only appear in post content. Please follow #41969 for style changes that are made to the coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. bundled themes to then also makemake A collection of P2 blogs at, which are the home to a number of contributor groups, including core development (make/core, formerly "wpdevel"), the UI working group (make/ui), translators (make/polyglots), the theme reviewers (make/themes), resources for plugin authors (make/plugins), and the accessibility working group (make/accessibility). similar changes to your themes.


The gallery widget was first introduced and tested in the Core Media Widgets feature pluginFeature Plugin A plugin that was created with the intention of eventually being proposed for inclusion in WordPress Core. See Features as Plugins.. The pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the Plugin Directory or can be cost-based plugin from a third-party is developed on GitHub and the issues and pull requests related to the gallery widget can be reviewed there for a full history of the feature.

Please report new issues on Trac in the Widgets component, after first checking for any existing Gallery widget tickets.

#4-9, #dev-notes