Combobox framework documentation

An adaptable framework for building accessible comboboxes. Built as a web component, it can be used in any framework or vanilla HTML/CSS/JS.

Key features

  • Accessible! Built to follow the WAI-ARIA combobox design pattern. Built for keyboard navigation, screen readers, and other assistive technologies.
  • Easy to style! Bind your own elements to the framework slots, and style them however you want. Easy to integrate into any design system.

What follows are examples of how to use/implement the combobox-framework component

Installation

Link in from CDN

<script type="module" src="https://unpkg.com/combobox-framework"></script>

Install from npm

Install the combobox-framework from npm

npm install combobox-framework

Import the combobox-framework into your project

import 'combobox-framework';

Demo

A "real world" example of how the combobox-framework can be used. Meant to show how the search functionality can be used with a larger dataset (91 options).

The example is a combobox-framework with a input and a table of cast members from the movie The Shawshank Redemption. The input is used to search for a cast member, and the table is used to show the cast members.

Note: The focus of this demo is not on the styling, but on the functionality of the combobox-framework.

Name Role
Tim Robbins Andy Dufresne
Morgan Freeman Ellis Boyd "Red" Redding
Bob Gunton Warden Samuel Norton
William Sadler Heywood
Clancy Brown Byron Hadley
Gil Bellows Tommy Williams
James Whitmore Brooks Hatlen
Mark Rolston Bogs Diamond
Jeffrey DeMunn 1946 D.A.
Larry Brandenburg Skeet
Neil Giuntoli Jigger
Brian Libby Floyd
David Proval Snooze
Joseph Ragno Ernie
Jude Ciccolella Guard Mert
Paul McCrane Guard Trout
Renee Blaine Linda Dufresne (Andy Dufresne's Wife)
Scott Mann Glenn Quentin
John Horton Lloyd Henreid (Judge)
Gordon Greene 1947 Parole Hearings Man
Alfonso Freeman Fresh Fish Con
V.J. Foster Hungry Fish Con (as V.J. Foster)
John E. Summers New Fish Guard
Frank Medrano Fat Ass
Mack Miles Tyrell
Alan R. Kessler Laundry Bob
Morgan Lund Laundry Truck Driver
Cornell Wallace Laundry Leonard
Gary Lee Davis Rooster
Neil Summers Pete
Ned Bellamy Guard Youngblood
Joe Pecoraro Projectionist
Harold E. Cope Jr. Hole Guard
Brian Delate Guard Dekins
Don McManus Guard Wiley
Dorothy Silver Landlady
Donald Zinn Moresby Batter
Robert Haley 1954 Food-Way Manager
Dana Snyder 1954 Food-Way Proprietor
John D. Craig 1954 Food-Way Customer
Ken Magee Ned Grimes
Eugene C. DePasquale Mail Caller
Bill Bolender Elmo Blatch
Ron Newell Elderly Hole Guard
John R. Woodward Bullhorn Tower Guard
Chuck Brauchler Man Missing Guard
Dion Anderson Head Bull Haig
Claire Slemmer Bank Teller
James Kisicki Bank Manager
Rohn Thomas Bugle Editor
Charlie Kearns 1966 D.A
Rob Reider Duty Guard
Brian Brophy 1967 Parole Hearings Man
Paul Kennedy 1967 Food-Way Manager
John D. Craig Old Man on Bus (uncredited)
Fred Culbertson Police Officer (uncredited)
Richard Doone Con (uncredited)
Samantha Goldberg Bank Employee (uncredited)
Shane Grove Inmate (uncredited)
Rita Hayworth Gilda Mundson Farrell (archive footage) (uncredited)
Bill McKinney Bank Teller
Alonzo F. Jones Inmate (uncredited)
Gary Jones Convict (uncredited)
Sergio Kato Inmate II (uncredited)
Michael Lightsey Con (uncredited)
Tracy Love Court Spectator (uncredited)
George Macready Ballin Mundson (archive footage) (uncredited)
Christopher Page Traffic (driver) (uncredited)
Neil Riddaway Con (uncredited)
Brad Spencer 1957 Parole Hearings Guard (uncredited)
Jodiviah Stepp New Fish Con (uncredited)
Mark A. Strain Yard Inmate (uncredited)
James Babson Con (uncredited)
Dennis Baker Old Man on Bus (uncredited)
Fred Culbertson Police Officer (uncredited)
Richard Doone Con (uncredited)
Samantha Goldberg Bank Employee (uncredited)
Shane Grove Inmate (uncredited)
Rita Hayworth Gilda Mundson Farrell (archive footage) (uncredited)
David Hecht Bank Teller
Alonzo F. Jones Inmate (uncredited)
Gary Jones Convict (uncredited)
Sergio Kato Inmate II (uncredited)
Michael Lightsey Con (uncredited)
Tracy Love Court Spectator (uncredited)
George Macready Ballin Mundson (archive footage) (uncredited)
Christopher Page Traffic (driver) (uncredited)
Neil Riddaway Con (uncredited)
Brad Spencer 1957 Parole Hearings Guard (uncredited)
Jodiviah Stepp New Fish Con (uncredited)
Mark A. Strain Yard Inmate (uncredited)

Examples

Simple list

To use the combobox-framework, you need to add a input element and a list of items. The input element needs to be placed in a slot="input" attribute and the list of items needs to be placed in a slot="list" attribute.

The li elements needs to have a data-value attribute. This is the value that will be set on the combobox-framework element as the data-value when a option is selected.

  • Item 1
  • Item 2
  • Item 3
  • Item 4

Simple list with custom display data

To show diffrent data in the input than in the list, you need to add the data-display attribute to the li element. This is the value that will be shown in the input when a option is selected.

  • 1
  • 2
  • 3
  • 4

List with nested elements

To use nested elements, you need to add the data-display attribute to the li element. This is the value that will be shown in the input when a option is selected.

  • Item 1
  • Item 2
  • Item 3
  • Item 4

Tabular data

To use tabular data, you need to add the data-list attribute to the tbody element. This will tell the combobox-framework to use the tbody element as the list of items and not the table itself.

Name Number
Item 1
Item 2
Item 3
Item 4

Preselected option

To preselect a option, you need to add the data-value attribute to the combobox-framework element. This will tell the combobox-framework to select the option with the matching data-value attribute.

  • Item 1
  • Item 2
  • Item 3
  • Item 4

Custom Fuse/Fuzzy search options

To use custom fuse/fuzzy search options, you need to add the data-fuse-options attribute to the combobox-framework element, and pass in a JSON string of the settings object. This will tell the combobox-framework to use the custom options when searching for a option.

For what options are available, see the Fuse.js documentation

  • Item 1
  • Item 2
  • Item 3
  • Item 4

Force value/Listbox

To force the combobox-framework to act as a searchable listbox, you need to add the data-listbox attribute to the combobox-framework element. This will tell the combobox-framework to act as a searchable listbox instead of a combobox. And only allow the value to be one of the options in the list or null.

  • Item 1
  • Item 2
  • Item 3
  • Item 4

Limit suggested options

To limit the number of suggested options, you need to add the data-limit attribute to the combobox-framework element. This will tell the combobox-framework to only show the number of options specified in the data-limit attribute.

  • Item 1
  • Item 2
  • Item 3
  • Item 4

To use weighted item search, you need to add the data-weight attribute to the li element. This is the value that will be used to sort the options when searching for a option.

NOTE: Fuse options must have includeScore set to true for weighted search to work. includeScore is true by default, if you have not set custom fuse options.

NOTE: The data-weight attribute is a number, and the higher the number the higher the weight.

  • Item 1
  • Item 2
  • Item 3
  • Item 4

Change events

To add a change event, you need to add the onchange attribute to the combobox-framework element. This will tell the combobox-framework to run the function when the value of the combobox changes.

  • Item 1
  • Item 2
  • Item 3
  • Item 4

Styling

This is the styling thats being used on this demo page. Hopefully it gives a good starting point