Content creation UX wonderland with Entity browser

Janez Urevc / @slashrsm /

Janez Urevc (@slashrsm)

  • senior engineer and team lead at MD Systems
  • Active member of Drupal community since 2009
  • Lead of the D8 media initiative
  • ex

Among top contributors

  • our CTO (@berdir) is one of top 5 D8 contributors
  • D8 expert
  • D8 media expert - lots of media clients
  • 20% of every project to the community
  • Services include: Full projects, site audits, bootstrap weeks, support/consulting, architecture planning, ...

Contents of the session

  • What is entity browser?
  • Architecture
  • Where can I use it?
  • Examples/Covered use cases
  • Inline entity form integration
  • Roadmap

Have you ever...

...wanted to upload multiple images at once?

...wanted to select images from a media library?

...thought about combining both?

...tried to search for related content?

...needed to create a related entity without leaving the context?

We've got you covered!

* no BS attached

What is entity browser?

General entity browsing, selecting and creating tool. Works with any entity type. Can work with fields, WYSIWYG, custom forms, ...


Powerful, flexible, pluggable* and extensible.

*yes, it heavily relies on core plugin system


Widget (cont'd)

Part that decides which entities are "selected" on a given step. Can be:

  • a view - listing of entities*
  • file uploader (HTML5*, DropzoneJS*, ...)
  • remote resource browser (YouTube, Flickr, Getty images, ...)
  • entity form*
  • ...

Widget (cont'd)

interface WidgetInterface {

  public function getForm(array &$original_form, FormStateInterface $form_state, array $aditional_widget_parameters);

  public function validate(array &$form, FormStateInterface $form_state);

  // Call WidgetBase::selectEntities() to propagate selection to the other parts
  // of the entity browser (event).
  public function submit(array &$element, array &$form, FormStateInterface $form_state);


Widget selector

Widget selector (cont'd)

Part that defines how switching between widgets work. Can be:

  • single widget - only one widget is used, no need to allow selection*
  • dropdown*
  • buttons*
  • tabs*
  • ...

Widget selector (cont'd)

interface WidgetSelectorInterface {

  public function getForm(array &$form, FormStateInterface &$form_state);

  public function setDefaultWidget($widget);

  public function validate(array &$form, FormStateInterface $form_state);

  // Return UUID of the selected widget.
  public function submit(array &$form, FormStateInterface $form_state);


Selection display

Selection display (cont'd)

Part that displays entities that are currently selected. Can be:

  • no display - only one step of selection is possible, entities are propagated immediately*
  • view display*
  • rendered entity display*
  • entity label*
  • ...

Selection display (cont'd)

interface SelectionDisplayInterface {

  public function getForm(array &$original_form, FormStateInterface $form_state);

  public function validate(array &$form, FormStateInterface $form_state);

  // Call SelectionDisplayBase::selectionDone() to finish "session" and return
  // selected entities (event).
  public function submit(array &$form, FormStateInterface $form_state);



Defines how entity browser appears in the broader context. Can be:

  • iFrame*
  • modal*
  • standalone*
  • ...

Display (cont'd)

interface DisplayInterface {

  // Some members ommitted for simplification ...
  public function displayEntityBrowser(FormStateInterface $form_state);

  public function selectionCompleted(array $entities);
  // ...


Where can I use Entity browser today?

As an entity reference field widget

As a file/image field widget

In Entity embed

In a custom form

// There is a form element. See \Drupal\entity_browser\Element\EntityBrowserElement
// for more info.
$form['entity_ids'] = [
  '#type' => 'entity_browser',
  '#entity_browser' => 'my_test_entity_browser',
  '#cardinality' => 5,

Example: upload images and select from library

Inline entity form integration

Powerful entity reference widget, that allows creation/edit of referenced entities inline.

You can use Entity browser with its "Use existing" feature.


Very close to beta: fix critical bugs

Other things: UX, tests

You can use it!
(Lightning, Thunder, NP8 and many more do already.)

We need help!

#drupal-media on IRC, meeting every Wednesday 14:00 UTC

We need help!

Join us on contribution sprints on Friday.

First Time Sprinter Workshop - 9:00-12:00 - Room Wicklow 2A

Mentored Core Sprint - 9:00-18:00 - Wicklow Hall 2B

General Sprints - 9:00 - 18:00 - Wicklow Hall 2A

Thank you! Questions?

Leave feedback: https//

Janez Urevc / @slashrsm /