@gitlab/ui

A disclosure dropdown is a button that toggles a panel containing a list of actions and/or links. Use [this decision tree](https://design.gitlab.com/components/dropdown-overview#which-component-should-you-use) to make sure this is the right dropdown component for you. ## Basic usage ```html <gl-disclosure-dropdown toggle-text="Actions" :items="items" /> ``` ## Icon-only disclosure dropdown Icon-only disclosure dropdowns must have an accessible name. You can provide this with the combination of `toggleText` and `textSrOnly` props. Optionally, you can use `no-caret` to remove the caret and `category="tertiary"` to remove the border. ```html <gl-disclosure-dropdown icon="ellipsis_v" toggle-text="Actions" text-sr-only category="tertiary" no-caret /> ``` ## Opening the disclosure dropdown Disclosure dropdown will open on toggle button click (if it was previously closed). On open, `GlDisclosureDropdown` will emit the `shown` event. ## Closing the disclosure dropdown The disclosure dropdown is closed by any of the following: - pressing <kbd>Esc</kbd> - clicking anywhere outside the component - clicking the action or link inside the dropdown Before closing, `GlDisclosureDropdown` emits a `beforeClose` event with these properties: 1. `originalEvent` – the event that triggered closing of the dropdown 2. `preventDefault` – a method which will prevent closing of the dropdown An example of using this event to prevent the dropdown from closing: ```html <gl-disclosure-dropdown @beforeClose="$event.preventDefault()" /> ``` Note that this method will also prevent the dropdown from closing even if the trigger button is clicked. You can use the `preventDefault` to filter out events that are causing undesired dropdown closing: ```html <gl-disclosure-dropdown @beforeClose="(e) => { ignoreElement.contains(e.originalEvent.target) && e.preventDefault() }" /> ``` After closing, `GlDisclosureDropdown` emits a `hidden` event. ## Setting disclosure dropdown items Use the `items` prop to provide actions/links to the disclosure dropdown. Each item can be either an item or a group. For `Item`s, provide an `href` or `to` string to make them render as links. Otherwise, they will be buttons. Provide an `action` function to items to be called when they are pressed, or, listen for the `action` event on the top-level component. Both will receive the given item as an argument. A  [validation error](https://gitlab.com/gitlab-org/gitlab-ui/-/blob/6cbff4f908b429cc01f17a4cc2868e881db1aa31/src/components/base/new_dropdowns/disclosure/utils.js#L1) will be triggered if neither field is set. Below are the expected shapes of these objects: ```typescript type Item = { // The item text text: string; // href link href?: string; // or, a Vue router link with `to` to?: string; // Item action action?: (item: Item) => void; // Set of extra attributes applied directly to the element extraAttrs?: Object; // Additional class/classes applied to the item wrapper wrapperClass?: string; }; type Group = { // Name of the group, used as a header name?: string; // Items of the group items: Array<Item>; // Set of extra attributes applied directly to the element extraAttrs?: Object; }; type ItemsProp = Array<Item> | Array<Group>; ``` ### Actions/links The `text` property is used to render the default disclosure dropdown item template. If you want to render a custom template for items, use the `list-item` scoped slot: ```html <gl-disclosure-dropdown :items="items"> <template #list-item="{ item }"> <span class="gl-display-flex gl-align-items-center gl-justify-content-space-between"> {{item.text}} <gl-icon v-if="item.icon" :name="item.icon" /> </span> </template> </gl-disclosure-dropdown> ``` ### Groups Actions/links can be contained within groups. A group can have a `name` property, which will be used as the group header if present. It also has a required property `items` that must be an array of links/actions. Groups can be at most one level deep: a group can only contain actions/links. Items and groups _cannot_ be siblings. Either all items are actions/links, or they are all groups. To render custom group labels, use the `group-label` scoped slot: ```html <gl-disclosure-dropdown :items="groups"> <template #group-label="{ group }"> {{ group.name }} <gl-badge size="sm">{{ group.items.length }}</gl-badge> </template> </gl-disclosure-dropdown> ``` To draw a horizontal line that separates two groups, set the `bordered` property. By default, the border appears above the group. You can change the border position using the `border-position` property: ```html <gl-disclosure-dropdown> <gl-disclosure-dropdown-group bordered border-position="bottom" :group="group" /> </gl-disclosure-dropdown> ``` ### Miscellaneous content Besides default components, disclosure dropdown can render miscellaneous content inside it. In this case the user is responsible for handling all events and navigation inside the disclosure. ### Dealing with long option texts - Some options might have long non-wrapping text that would overflow the dropdown maximum width. In such cases, it's recommended to override the `#list-item` slot and to truncate the option text using `GlTruncate`. - If the toggle text reflects the selected option text, it might be necessary to truncate it too by overriding the `#toggle` slot. ## Split dropdown See [button group documentation](/docs/base-button-group--docs#split-dropdowns).