The collection-browser element

Overview

The <collection-browser> element is a container that manages a collection of children as a gallery of items for interaction.

It provides selection events and an add button for invoking handlers to add new items to the collection.

It also provides a category slot which can be used to filter the children, either with built-in handling, or by using custom event handlers.

Basic Examples

Embedded

The <collection-browser> element can be used directly on the page, as an isolated gallery.

Category 1
Category 2
Category 3
Category 4
A
B
C
D
E

Dialog

The <collection-browser> element can also be used within a <dialog> element to mimic a "File Browser".

Use the button, below, to open the dialog example. Note that this example's <collection-browser> element has a multi attribute, so multiple items may be selected.

Custom Collection Browser
Category 1
Category 2
Category 3
Category 4
A
B
C
D
E

No Categories

The <collection-browser> element can be used without any categories, if items do not need to be filtered.

A
B
C
D
E

No Add Button

The <collection-browser> element's "Add" button is in the header part, which can be removed by setting its display style property to none.

In this example, the entire header part has been hidden by setting its display value to none, rather than directly removing the "Add" button:

Category 1
Category 2
A
B
C
D
E

Categories

The <collection-browser> element provides a slot with the name category as a method to navigate through, or filter the items in the collection browser.

Category elements, like the item elements, can be any element type. To make an element a category, set it's slot attribute to category.

Each category element will trigger a category event when it is clicked. It also has the default functionality of add selected to its own class list, as well as adding the class has-category to any item that matches the category's key.

Matching is done with an exact string match of the data-category attribute for each category element and each item element. For default matching, set a category element's data-category value to any value, then set an item's data-category value to that same value. When the category is clicked, the item will get a has-category class.

Items may use multiple category keys by separating them with a comma (,) character. For instance, an item with the attribute data-category="a,b,c" would match for any category that had a key of "a", "b", or "c".

Default functionality can be prevented by handling the category event and calling the preventDefault() function on the event object.

In this example, the has-category class adds a border so the filtered elements can be seen. To demonstrate multiple categories, the last three elements - J, K, and L - each use multiple categories so that they all match for category 4, but each match for another category, as well.

Category 1
Category 2
Category 3
Category 4
A
B
C
D
E
F
G
H
I
J
K
L

The <captioned-thumbnail> and <collection-filter> elements

The <captioned-thumbnail> Element

The <collection-browser> element can be used within a <dialog> element to mimic a "File Browser".

Use the button, below, to open the dialog example. Note that this example's <collection-browser> element has a multi attribute, so multiple items may be selected.

Custom Collection Browser
Drives
Drive 1
Drive 2
Drive 3
Drive 4
First Second Third Fourth Fifth Sixth Seventh Eigth Ninth Tenth Eleventh Twelfth Thirteenth Fourteenth Fifteenth Sixteenth Seventeenth Eighteenth Ninteenth Twentieth Twenty-First Twenty-Second Twenty-Third Twenty-Fourth
Tip: Select multiple items by holding Shift or Ctrl, or by selecting with the checkboxes.

The <collection-filter> Element

The <collection-browser> element's items can be searched by adding the custom <collection-filter> element.

The <collection-filter> element prepares a query and then provides that query as detail data on an event. Using that data, the items can be filtered to present the browser's items in their most relevant order.

In the example below, the items that match the provided search term will be given a border and moved to the front of the collection, while the other items will have their opacity lowered.

Try searching for "teen", for example:

Custom Collection Browser
First Second Third Fourth Fifth Sixth Seventh Eigth Ninth Tenth Eleventh Twelfth Thirteenth Fourteenth Fifteenth Sixteenth Seventeenth Eighteenth Ninteenth Twentieth Twenty-First Twenty-Second Twenty-Third Twenty-Fourth

Events

The <collection-browser> element dispatches three event types: change, category, and add

Whenever an item is selected, the change event is dispatched.

Whenever a category is selected, the category event is dispatched.

Whenever the add button is clicked, the add event is dispatched.

In the example below, each event is handled by adding an entry with the event's details in the entry log:

Category 1
Category 2
Category 3
Category 4
A
B
C
D
E
F
G
H
I
J
K
Event Log

    Nested Slots

    The <collection-browser> element dispatches three event types: change, category, and add

    Whenever an item is selected, the change event is dispatched.

    Whenever a category is selected, the category event is dispatched.

    Whenever the add button is clicked, the add event is dispatched.

    In the example below, each event is handled by adding an entry with the event's details in the entry log:

    Drives
    Drive 1
    Drive 2
    Drive 3
    Drive 4
    First Second Third Fourth Fifth Sixth Seventh Eigth Ninth Tenth Eleventh Twelfth Thirteenth Fourteenth Fifteenth Sixteenth Seventeenth Eighteenth Ninteenth Twentieth Twenty-First Twenty-Second Twenty-Third Twenty-Fourth
    Event Log