An Origami component for selecting multiple options.

• o-multi-select
  • Usage
  • Markup
    • Using TSX templates
  • Sass
  • JavaScript
  • Keyboard Support
    • When focus is within the combobox input and the suggestions menu is closed
    • When focus is within the suggestions menu
  • Migration
  • Contact
  • Licence

Check out how to include Origami components in your project to get started with o-multi-select.

o-multi-select expects options to be provided in a <select> tag. The component will automatically enhance the experience for users with JavaScript enabled.

The value must not contain whitespace characters, as it should be valid as an id attribute

<div class="o-multi-select" data-o-component="o-multi-select">
	<select name="multiple" id="fruits" multiple>
		<option value="Apple">Apple</option>
		<option value="Banana">Banana</option>
		<!--More options -->
	</select>
</div>

To style form labels, we recommend using o-forms.

Below is an example of how to combine o-forms and o-multi-select components together. Note the label and select element are connected using for and id attributes.

<form data-o-component="o-forms">
	<label for="fruits" class="o-forms-field">
		<span class="o-forms-title">
			<span class="o-forms-title__main">Select multiple options</span>
		</span>
	</label>
	<div class="o-forms-input">
		<div class="o-multi-select" data-o-component="o-multi-select">
			<select name="multiple" id="fruits" multiple>
				<option value="Apple">Apple</option>
				<option value="Banana">Banana</option>
				<!--More options -->
			</select>
		</div>
	</div>
</form>

If you are using TSX templates we recommend that you also import GenericInput and Form from o-forms. This will style labels and options for your TSX component. And you will also need to initialise component javascript in correct lifecycle of your competent. Bellow is an example for react users.

import {Form, GenericInput} from '@financial-times/o-forms/src/tsx/Form';
import {MultiSelect} from '@financial-times/o-multi-select/src/tsx/multi-select';

export const MultiSelectDefault = args => {
	return (
		<Form>
			<GenericInput id={args.id} title={args.title}>
				<MultiSelect {...args} />
			</GenericInput>
		</Form>
	);
};

Use @include oMultiSelect() to include styles for all o-multi-select features.

@import '@financial-times/o-multi-select';

@include oMultiSelect();

JavaScript is initialised automatically for Origami Build Service users.

If your project is using a manual build process, initialise o-multi-select manually. For example call the init method to initialise all o-multi-select instances in the document:

import oMultiSelect from 'o-multi-select';
oMultiSelect.init();

Or pass an element to initialise a specific o-multi-select instance:

import oMultiSelect from 'o-multi-select';
const oMultiSelectElement = document.getElementById(
	'#my-o-multi-select-element'
);
oMultiSelect.init(oMultiSelectElement);

o-multi-select dispatches a custom event oMultiSelect.OptionChange that bubbles. It is triggered when an option gets selected or removed. The event data has the following interface:

detail: {
  optionElement: HTMLelement, // The elements that was selected or deselected
  value: string, // Value of selected/deselected option
  selected: boolean, // If element is selected or not
  index: number, // Index of option in the array of options
  instance, // Instance of multiselect element
}

If you have any questions or comments about this component, or need help using it, please either raise an issue, visit #origami-support or email origami.support@ft.com.

This software is published by the Financial Times under the MIT licence.