@gitlab/ui/dist/components/base/form/form_combobox/form_combobox.documentation.js

GitLab UI Components

import examples from './examples';

var form_combobox = "# GlFormCombobox\n\nUse this component to add a [`FormInput`](/?path=/story/base-form-form-input--default) component\nwith synchronous autocomplete dropdown. It behaves as follows:\n\n- Typing matches tokens; dropdown disappears when there is no match  \n- Up and down arrows navigate the dropdown  \n- Enter selects keyboard-highlighted item; clicking overrides this  \n- Esc closes dropdown when it is open, clears field when it is not  \n- Browser/native autocomplete dropdown hidden when ours is open, shows when it is not  \n- Tab selects current entered text and moves to next field  \n\nThis behavior based on\n[this w3c pattern](https://www.w3.org/TR/wai-aria-practices/examples/combobox/aria1.1pattern/listbox-combo.html)\nand [this accessible combobox example](https://alligator.io/vuejs/vue-a11y-autocomplete/).\n\n## Usage\n\nThe combobox accepts an array of string tokens, a `v-model`, and label text. Internally, it generates\nunique element IDs so multiple can be used on one page without clashing.\n\nOn selection it sets the input value to the selected string and emits a `value-selected` event for\nconsumption by parent components.\n\n```html\n<gl-form-combobox\n  v-model=\"inputVal\"\n  :token-list=\"tokens\"\n  label-text=\"Combobox Label\"\n/>\n```\n\nIt does not have a loading state nor does it accept tokens other than strings. It allows for one\nselected value.\n\n### What if I need to load the options asynchronously?\n\nYou may want to look at [`GlSearchBoxByType`] or [`GlSearchBoxByClick`].\n\n### What if I need multiple options?\n\nThe [`GlTokenSelector`] may be what you need. Alternately, [`GlFilteredSearch`] will let you search\nand include tokens.\n\n## Edge cases\n\nThe algorithm to match tokens with the input is very naive. If you need to use the component with a\nvery large list of matches, you may want to update the implementation or use one of the search\ninputs, like [`GlSearchBoxByType`], [`GlSearchBoxByClick`], or [`GlFilteredSearch`].\n\n[`GlSearchBoxByType`]: https://gitlab-org.gitlab.io/gitlab-ui/?path=/story/base-search-box-by-type--default\n[`GlSearchBoxByClick`]: https://gitlab-org.gitlab.io/gitlab-ui/?path=/story/base-search-box-by-click--default\n[`GlTokenSelector`]: https://gitlab-org.gitlab.io/gitlab-ui/?path=/story/base-token-selector--default\n[`GlFilteredSearch`]: https://gitlab-org.gitlab.io/gitlab-ui/?path=/story/base-filtered-search--default\n";

var description = /*#__PURE__*/Object.freeze({
  __proto__: null,
  'default': form_combobox
});

var form_combobox_documentation = {
  followsDesignSystem: true,
  description,
  examples,
  events: [{
    event: 'value-selected',
    description: 'Emitted when a value is selected.'
  }]
};

export default form_combobox_documentation;