Multi Select

yarn add @clayui/multi-select

Multi select is the field type that allows writing text to create “tags” that are represented in the shape of labels.

React Component
CSS / Markup

Composing
Custom Autocomplete
API

Multi Select is an aggregate component of the @clayui/form package, consisting of a high-level written above a <ClayInput /> that provides the ability to create tags.

import ClayMultiSelect from '@clayui/multi-select';

import ClayMultiSelect from '@clayui/multi-select';

const Component = () => {
  const [value, setValue] = useState("");
  const [items, setItems] = useState([
    {
      label: "one",
      value: "1"
    }
  ]);

  return (
    <ClayMultiSelect
      inputName="myInput"
      inputValue={value}
      items={items}
      onChange={setValue}
      onItemsChange={setItems}
      spritemap={spritemap}
    />
  );
};

render(<Component />);

const Component = () => {
  const [value, setValue] = useState("");
  const [items, setItems] = useState([
    {
      label: "one",
      value: "1"
    }
  ]);
  return (
    <ClayMultiSelect
      inputName="myInput"
      inputValue={value}
      items={items}
      onChange={setValue}
      onItemsChange={setItems}
      spritemap={spritemap}
    />
  );
};
render(<Component />);

Composing

<ClayMultiSelect /> enables you to make compositions to achieve your expected results, as this component is distributed only in a low level component, this increases flexibility and you can create many possibilities but it comes with a price tag... you may want to get close to the Lexicon specifications and will have to compose with some of the other components to get there, let's detail it further below.

Autocomplete

Usually a MultiSelect has an autocomplete to help the user choose existing tags. You can use the sourceItems API to achieve this result.

import ClayMultiSelect from '@clayui/multi-select';

import ClayMultiSelect from '@clayui/multi-select';

const Component = props => {
  const [value, setValue] = useState("");
  const [items, setItems] = useState([
    {
      label: "one",
      value: "1"
    }
  ]);

  const sourceItems = [
    {
      label: "one",
      value: "1"
    },
    {
      label: "two",
      value: "2"
    },
    {
      label: "three",
      value: "3"
    },
    {
      label: "four",
      value: "4"
    }
  ];

  return (
    <ClayMultiSelect
      {...props}
      inputName="myInput"
      inputValue={value}
      items={items}
      onChange={setValue}
      onItemsChange={setItems}
      sourceItems={sourceItems}
      spritemap={spritemap}
    />
  );
};

render(<Component />);

const Component = props => {
  const [value, setValue] = useState("");
  const [items, setItems] = useState([
    {
      label: "one",
      value: "1"
    }
  ]);
  const sourceItems = [
    {
      label: "one",
      value: "1"
    },
    {
      label: "two",
      value: "2"
    },
    {
      label: "three",
      value: "3"
    },
    {
      label: "four",
      value: "4"
    }
  ];
  return (
    <ClayMultiSelect
      {...props}
      inputName="myInput"
      inputValue={value}
      items={items}
      onChange={setValue}
      onItemsChange={setItems}
      sourceItems={sourceItems}
      spritemap={spritemap}
    />
  );
};
render(<Component />);

Select Button

According to the Lexicon specification a Select button can be grouped with MultiSelect to allow tag data to come from elsewhere. You can achieve this result by composing with <ClayForm.Group />, <ClayInput.GroupItem /> and <ClayButton /> .

import ClayButton from '@clayui/button';
import ClayForm, {ClayInput} from '@clayui/form';
import ClayMultiSelect from '@clayui/multi-select';

import ClayButton from '@clayui/button';
import ClayForm, {ClayInput} from '@clayui/form';
import ClayMultiSelect from '@clayui/multi-select';

const Component = () => {
  const [value, setValue] = useState("");
  const [items, setItems] = useState([
    {
      label: "one",
      value: "1"
    }
  ]);

  const sourceItems = [
    {
      label: "one",
      value: "1"
    },
    {
      label: "two",
      value: "2"
    },
    {
      label: "three",
      value: "3"
    },
    {
      label: "four",
      value: "4"
    }
  ];

  return (
    <ClayForm.Group>
      <ClayInput.Group>
        <ClayInput.GroupItem>
          <ClayMultiSelect
            inputName="myInput"
            inputValue={value}
            items={items}
            onChange={setValue}
            onItemsChange={setItems}
            sourceItems={sourceItems}
            spritemap={spritemap}
          />
        </ClayInput.GroupItem>
        <ClayInput.GroupItem shrink>
          <ClayButton displayType="secondary" onClick={() => alert("Click")}>
            {"Select"}
          </ClayButton>
        </ClayInput.GroupItem>
      </ClayInput.Group>
    </ClayForm.Group>
  );
};

render(<Component />);

const Component = () => {
  const [value, setValue] = useState("");
  const [items, setItems] = useState([
    {
      label: "one",
      value: "1"
    }
  ]);
  const sourceItems = [
    {
      label: "one",
      value: "1"
    },
    {
      label: "two",
      value: "2"
    },
    {
      label: "three",
      value: "3"
    },
    {
      label: "four",
      value: "4"
    }
  ];
  return (
    <ClayForm.Group>
      <ClayInput.Group>
        <ClayInput.GroupItem>
          <ClayMultiSelect
            inputName="myInput"
            inputValue={value}
            items={items}
            onChange={setValue}
            onItemsChange={setItems}
            sourceItems={sourceItems}
            spritemap={spritemap}
          />
        </ClayInput.GroupItem>
        <ClayInput.GroupItem shrink>
          <ClayButton displayType="secondary" onClick={() => alert("Click")}>
            {"Select"}
          </ClayButton>
        </ClayInput.GroupItem>
      </ClayInput.Group>
    </ClayForm.Group>
  );
};
render(<Component />);

Validation

An input needs validation so you can add some composition props with <ClayInput /> and <ClayForm /> to get the result.

MultiSelect

You made an error

import ClayButton from '@clayui/button';
import ClayForm, {ClayInput} from '@clayui/form';
import ClayMultiSelect from '@clayui/multi-select';

import ClayButton from '@clayui/button';
import ClayForm, {ClayInput} from '@clayui/form';
import ClayMultiSelect from '@clayui/multi-select';

const Component = () => {
  const [value, setValue] = useState("");
  const [items, setItems] = useState([
    {
      label: "one",
      value: "1"
    }
  ]);

  const sourceItems = [
    {
      label: "one",
      value: "1"
    },
    {
      label: "two",
      value: "2"
    },
    {
      label: "three",
      value: "3"
    },
    {
      label: "four",
      value: "4"
    }
  ];

  return (
    <ClayForm.Group className="has-error">
      <label>{"MultiSelect"}</label>

      <ClayInput.Group>
        <ClayInput.GroupItem>
          <ClayMultiSelect
            inputName="myInput"
            inputValue={value}
            items={items}
            onChange={setValue}
            onItemsChange={setItems}
            sourceItems={sourceItems}
            spritemap={spritemap}
          />

          <ClayForm.FeedbackGroup>
            <ClayForm.FeedbackItem>
              <ClayForm.FeedbackIndicator
                spritemap={spritemap}
                symbol="info-circle"
              />

              {"You made an error"}
            </ClayForm.FeedbackItem>
          </ClayForm.FeedbackGroup>
        </ClayInput.GroupItem>
        <ClayInput.GroupItem shrink>
          <ClayButton displayType="secondary" onClick={() => alert("Click")}>
            {"Select"}
          </ClayButton>
        </ClayInput.GroupItem>
      </ClayInput.Group>
    </ClayForm.Group>
  );
};

render(<Component />);

const Component = () => {
  const [value, setValue] = useState("");
  const [items, setItems] = useState([
    {
      label: "one",
      value: "1"
    }
  ]);
  const sourceItems = [
    {
      label: "one",
      value: "1"
    },
    {
      label: "two",
      value: "2"
    },
    {
      label: "three",
      value: "3"
    },
    {
      label: "four",
      value: "4"
    }
  ];
  return (
    <ClayForm.Group className="has-error">
      <label>{"MultiSelect"}</label>
      <ClayInput.Group>
        <ClayInput.GroupItem>
          <ClayMultiSelect
            inputName="myInput"
            inputValue={value}
            items={items}
            onChange={setValue}
            onItemsChange={setItems}
            sourceItems={sourceItems}
            spritemap={spritemap}
          />
          <ClayForm.FeedbackGroup>
            <ClayForm.FeedbackItem>
              <ClayForm.FeedbackIndicator
                spritemap={spritemap}
                symbol="info-circle"
              />
              {"You made an error"}
            </ClayForm.FeedbackItem>
          </ClayForm.FeedbackGroup>
        </ClayInput.GroupItem>
        <ClayInput.GroupItem shrink>
          <ClayButton displayType="secondary" onClick={() => alert("Click")}>
            {"Select"}
          </ClayButton>
        </ClayInput.GroupItem>
      </ClayInput.Group>
    </ClayForm.Group>
  );
};
render(<Component />);

Custom Autocomplete

To customize Autocomplete content to stylize to your needs and also have filter control, you can use the menuRenderer API.

import ClayMultiSelect from '@clayui/multi-select';

import ClayMultiSelect from '@clayui/multi-select';

const MenuCustom = ({
  inputValue,
  locator,
  onItemClick = () => {},
  sourceItems
}) => (
  <ClayDropDown.ItemList>
    {sourceItems
      .filter(item => inputValue && item[locator.label].match(inputValue))
      .map(item => (
        <ClayDropDown.Item
          key={item[locator.value]}
          onClick={() => onItemClick(item)}
        >
          <div className="autofit-row autofit-row-center">
            <div className="autofit-col mr-3">
              <ClaySticker className="sticker-user-icon" size="lg">
                <ClayIcon spritemap={spritemap} symbol="user" />
              </ClaySticker>
            </div>
            <div className="autofit-col">
              <strong>{item[locator.label]}</strong>
              <span>{item.email}</span>
            </div>
          </div>
        </ClayDropDown.Item>
      ))}
  </ClayDropDown.ItemList>
);

const Component = () => {
  const [value, setValue] = useState("");
  const [items, setItems] = useState([
    {
      email: "one@example.com",
      label: "One",
      value: "1"
    }
  ]);

  const sourceItems = [
    {
      email: "one@example.com",
      label: "One",
      value: "1"
    },
    {
      email: "two@example.com",
      label: "Two",
      value: "2"
    }
  ];

  return (
    <ClayMultiSelect
      inputName="myInput"
      inputValue={value}
      items={items}
      menuRenderer={MenuCustom}
      onChange={setValue}
      onItemsChange={setItems}
      sourceItems={sourceItems}
      spritemap={spritemap}
    />
  );
};

render(<Component />);

const MenuCustom = ({
  inputValue,
  locator,
  onItemClick = () => {},
  sourceItems
}) => (
  <ClayDropDown.ItemList>
    {sourceItems
      .filter(item => inputValue && item[locator.label].match(inputValue))
      .map(item => (
        <ClayDropDown.Item
          key={item[locator.value]}
          onClick={() => onItemClick(item)}
        >
          <div className="autofit-row autofit-row-center">
            <div className="autofit-col mr-3">
              <ClaySticker className="sticker-user-icon" size="lg">
                <ClayIcon spritemap={spritemap} symbol="user" />
              </ClaySticker>
            </div>
            <div className="autofit-col">
              <strong>{item[locator.label]}</strong>
              <span>{item.email}</span>
            </div>
          </div>
        </ClayDropDown.Item>
      ))}
  </ClayDropDown.ItemList>
);
const Component = () => {
  const [value, setValue] = useState("");
  const [items, setItems] = useState([
    {
      email: "one@example.com",
      label: "One",
      value: "1"
    }
  ]);
  const sourceItems = [
    {
      email: "one@example.com",
      label: "One",
      value: "1"
    },
    {
      email: "two@example.com",
      label: "Two",
      value: "2"
    }
  ];
  return (
    <ClayMultiSelect
      inputName="myInput"
      inputValue={value}
      items={items}
      menuRenderer={MenuCustom}
      onChange={setValue}
      onItemsChange={setItems}
      sourceItems={sourceItems}
      spritemap={spritemap}
    />
  );
};
render(<Component />);

API

Property	Type	Required	Default	Description
clearAllTitle	string	false	'Clear All'	Title for the `Clear All` button.
closeButtonAriaLabel	string	false	'Remove {0}'	Aria label for the Close button of the labels.
menuRenderer	React.FunctionComponent<IMenuRendererProps>	false	({ filter = defaultFilter, inputValue, locator, onItemClick = () => {}, sourceItems, }) => ( <ClayDropDown.ItemList> {sourceItems .filter((item) => filter(item, inputValue, locator)) .map((item) => ( <ClayAutocomplete.Item key={item[locator.value]} match={inputValue} onClick={() => onItemClick(item)} value={item[locator.label]} /> ))} </ClayDropDown.ItemList> )	Adds a component to replace the default component that renders the content of the `<ClayDropDown />` component.
disabled	boolean	false		Flag that indicates to disable all features of the component.
disabledClearAll	boolean	false		Flag to disabled Clear All functionality.
filter	(item: Item, inputValue: string, locator: Locator) => boolean	false	(item: Item, inputValue: string, locator: Locator) => inputValue && item[locator.label].match(inputValue)	Callback to filter items based on the inputValue and locator
inputName	string	false		Value used for each selected item's hidden input name attribute
inputValue	string	false	''	Value of input
isValid	boolean	false	true	Flag to indicate if input is valid or not
items	Array<Item>	false	[]	Values that display as label items
locator	{ label: string; value: string; }	false	{ label: 'label', value: 'value', }	Sets the name of the field to map the value/label of the item
onClearAllButtonClick	() => void	false	() => { onItemsChange([]); onChange(''); }	Callback for when the clear all button is clicked
onChange	(val: any) => void	false	noop	Callback for when the input value changes
onItemsChange	(val: Array<Item>) => void	false	noop	Callback for when items are added or removed
sourceItems	Array<Item>	false	[]	List of pre-populated items that will show up in a dropdown menu
spritemap	string	false		Path to spritemap for clay icons
onBlur		false	noop
onFocus		false	noop
onKeyDown		false	noop
onPaste		false	noop

Example
Labels
Loading
Contenteditable Elements

Don't forget to check WAI-ARIA accessibility pratices for grids when writting your markup.

Don't forget to check WAI-ARIA accessibility pratices for search when writting your markup.

Example

This requires external javascript to populate, add labels, and show/hide the dropdown-menu.

Labels

Loading

Contenteditable Elements

Label

You can use a comma to enter tags.

<div class="form-group">
	<label for="formControlContentEditable1">Label</label>
	<div class="input-group input-group-stacked-sm-down">
		<div class="input-group-item">
			<div class="dropdown">
				<div class="form-control form-control-tag-group">
					<span class="autofit-row">
						<span class="autofit-col autofit-col-expand">
							<textarea
								aria-hidden="true"
								class="form-control-hidden"
								id="formControlContentEditable1"
								tabindex="-1"
							></textarea>
							<div
								class="form-control-inset"
								contenteditable="true"
							></div>
						</span>
					</span>
				</div>
				<ul class="autocomplete-dropdown-menu dropdown-menu">
					<li>
						<a class="dropdown-item" href="#1"
							><strong>some value</strong></a
						>
					</li>
					<li>
						<a class="dropdown-item" href="#1"
							><strong>some value</strong> meal</a
						>
					</li>
				</ul>
			</div>
			<div class="form-feedback-group">
				<div class="form-text">You can use a comma to enter tags.</div>
			</div>
		</div>
		<div class="input-group-item input-group-item-shrink">
			<button class="btn btn-secondary" type="submit">Select</button>
		</div>
	</div>
</div>