Holistics Design System

Dropdown ​

Stable

Allow users to choose one option from a floating list.

vue
<script setup lang="ts">
import { type DropdownOption, HDropdown, HButton } from '@holistics/design-system'

const options = [
  { key: '1', label: 'First item' },
  { key: '2', label: 'Second item' },
  { key: '3', label: 'Third item' },
] as const satisfies DropdownOption[]
</script>

<template>
  <HDropdown :options="options">
    <HButton type="primary-highlight">
      Open
    </HButton>
  </HDropdown>
</template>

Examples ​

Option Types ​

vue
<script setup lang="ts">
import { type DropdownOption, HDropdown, HButton } from '@holistics/design-system'

const options = [
  { key: '1', label: 'First item' },
  { key: '2', label: 'Second item' },
  { key: '3', label: 'Third item' },
] as const satisfies DropdownOption[]
</script>

<template>
  <HDropdown :options="options">
    <HButton type="primary-highlight">
      Default
    </HButton>
  </HDropdown>
</template>
vue
<script setup lang="ts">
import { type DropdownOption, HDropdown, HButton } from '@holistics/design-system'

const options = [
  { key: '1', label: 'First item' },
  { key: '2', label: 'Second item' },
  { type: 'divider' },
  { key: '3', label: 'Third item' },
] as const satisfies DropdownOption[]
</script>

<template>
  <HDropdown :options="options">
    <HButton type="primary-highlight">
      Divider
    </HButton>
  </HDropdown>
</template>
vue
<script setup lang="ts">
import { type DropdownOption, HDropdown, HButton } from '@holistics/design-system'

const options = [
  { key: '1', label: 'First item' },
  { key: '2', label: 'Second item' },
  { key: '3', label: 'Third item' },
  { type: 'group', key: 'group-1', label: 'With icons' },
  { key: '4', label: 'Fourth item', icons: ['data-model'] },
  { key: '5', label: 'Fifth item', icons: ['data-model', 'data-model'] },
  { key: '6', label: 'Sixth item', icons: ['data-model', 'data-model', 'data-model'] },
] as const satisfies DropdownOption[]
</script>

<template>
  <HDropdown :options="options">
    <HButton type="primary-highlight">
      Group
    </HButton>
  </HDropdown>
</template>
vue
<script setup lang="ts">
import { type DropdownOption, HDropdown, HButton } from '@holistics/design-system'

const options = [
  { key: '1', label: 'First item' },
  { key: '2', label: 'Second item' },
  { key: '3', label: 'Third item' },
  {
    key: '4',
    label: 'Nested Item',
    children: [
      { key: '8-1', label: 'Level 2 Item 1' },
      { key: '8-2', label: 'Level 2 Item 2', icons: 'data-model' },
      { type: 'divider' },
      {
        key: '8-3',
        label: 'More Nested (hover me)',
        icons: 'data-model',
        children: [
          { key: '8-3-1', label: 'Level 3 Item 1' },
          {
            key: '8-3-2',
            label: 'No more!',
            icons: 'lock',
            disabled: true,
            children: [
              { key: '7-3-2-1', label: 'Look me in the eye' },
              { key: '7-3-2-2', label: 'Tell me what you see' },
            ],
          },
        ],
      },
    ],
  },
] as const satisfies DropdownOption[]
</script>

<template>
  <HDropdown :options="options">
    <HButton type="primary-highlight">
      Nested
    </HButton>
  </HDropdown>
</template>
vue
<script setup lang="ts">
import { h } from 'vue'
import { type DropdownOption, HDropdown, HButton } from '@holistics/design-system'
import RenderComponent from './_RenderComponent.vue'

const options: DropdownOption[] = [
  // @ts-ignore Mismatch Vue version of `h()` function
  { type: 'render', render: (renderProps) => h(RenderComponent, { renderProps }) },
  { key: '1', label: 'First item' },
  { key: '2', label: 'Second item' },
  { key: '3', label: 'Third item' },
]
</script>

<template>
  <HDropdown :options="options">
    <HButton type="primary-highlight">
      Render
    </HButton>
  </HDropdown>
</template>
vue
<script setup lang="ts">
import { type DropdownOptionSlotProps, HIcon } from '@holistics/design-system'

const props = defineProps<{
  renderProps: DropdownOptionSlotProps
}>()

const { keyField, labelField } = props.renderProps
</script>

<template>
  <div>
    <div class="flex items-center p-4">
      <div class="flex size-10 items-center justify-center overflow-hidden rounded-full border border-gray-500">
        <HIcon
          size="lg"
          name="data-model"
        />
      </div>

      <div class="ml-2">
        <div class="text-base font-bold">
          Wonderful Data Model
        </div>
        <div class="mt-0.5 text-xs italic text-gray-600">
          Last edited: {{ new Date().toLocaleString() }}
        </div>
      </div>
    </div>

    <hr class="mx-auto mt-1 w-3/4">
    <div class="p-1 text-center text-2xs italic text-gray-500">
      (Key field: <code>"{{ keyField }}"</code>, Label field: <code>"{{ labelField }}"</code>)
    </div>
  </div>
</template>
vue
<script setup lang="ts">
import { type DropdownOption, HDropdown, HButton } from '@holistics/design-system'

const options = [
  { key: '1', label: 'First item' },
  { key: '2', label: 'Second item' },
  { key: '3', label: 'Third item' },
  { key: 'option-slot', slot: 'option-slot' },
] as const satisfies DropdownOption[]
</script>

<template>
  <HDropdown :options="options">
    <HButton type="primary-highlight">
      Slot
    </HButton>

    <template #option-slot="{ keyField, labelField }">
      <div class="flex items-center justify-between p-2">
        <span class="font-bold text-red-500">Key: {{ keyField }}</span>
        <span class="ml-2 italic text-green-600">Label: {{ labelField }}</span>
      </div>
    </template>
  </HDropdown>
</template>

Custom CSS & Styles for Options ​

vue
<script setup lang="ts">
import { type DropdownOption, HDropdown, HButton } from '@holistics/design-system'

const options = [
  {
    key: 'custom-css-default',
    label: 'I look like a Default Option, but my text is blue, bold, and italic!',
    class: 'text-blue-600 font-bold italic',
    icons: 'data-model',
  },
  { type: 'divider' },
  {
    type: 'group',
    key: 'custom-css-group',
    label: '(Truely) Disabled Group',
    class: 'text-red-500',
    icons: 'cancel',
  },
  {
    key: 'custom-css-disabled-item-guide',
    label: "Can you see the thickness of the divider right below? It's 20px!",
    disabled: true,
    class: 'italic',
    icons: 'arrow-down',
  },
  {
    type: 'divider',
    style: { 'border-top-width': '20px' },
  },
  {
    key: 'option',
    label: 'Normal Option',
  },
] as const satisfies DropdownOption[]
</script>

<template>
  <HDropdown :options="options">
    <HButton type="primary-highlight">
      Open
    </HButton>
  </HDropdown>
</template>

API ​

Pass-through: <HPopper> ​

What does this mean?

All props, events, and attrs that are not specified in the tables below will be passed to the element/component described above.

Props ​

NameTypeDescription
options *
Readonly<DropdownOption<any, "key", "label">>[]
disabled 
boolean

When true, disable Popper functinalities entirely.

anchor 
PopperAnchorRect | PopperAnchorElement

Anchor element. Can be an object with coordinates or a virtual element.

{@link https://floating-ui.com/docs/virtual-elements}

safeAreaDuration 
number

Duration (ms) of the safe area to exist before closing.

disableOutsidePointerEvents 
boolean

When true, only the top layer with disableOutsidePointerEvents = true has pointer-events: auto, all lower layers will have pointer-events: none

To interact with any element within lower layers, user will need to click outside of all layers with disableOutsidePointerEvents = true until reaching the desired element.

This can be used as a way to force all lower layers to not emit @pointer-down-outside while this layer is rendered.

strategy 
Strategy

The type of CSS position property to use. This could affect the positioning computation of the Floating element.

{@link https://floating-ui.com/docs/computeposition#strategy}

disableTransform 
boolean

By default, the Floating element is positioned using transform. This is the most performant way to position elements. However, transform will create a new stacking context which could be problematic in some cases. For example, if there is a position: fixed element inside the Floating element that expects to be calculated against the viewport, transform positioning will place that element incorrectly, hence need to be disabled.

{@link https://floating-ui.com/docs/vue#disabling-transform}

placement 
Placement
= "bottom-start"

The placement of the Floating element relative to the Anchor element.

{@link https://floating-ui.com/docs/computeposition#placement}

distance 
number
= 2

The distance between the Floating element and the Anchor element (applied on the axis that runs along the side of the Floating element).

{@link https://floating-ui.com/docs/offset#mainaxis}

skidding 
number

The skidding between the Floating element and the Anchor element (applied on the axis that runs along the alignment of the Floating element).

{@link https://floating-ui.com/docs/offset#crossaxis}

allowCollisions 
boolean

Whether to allow the Floating element to collide with the boundary.

collisionBoundary 
Boundary

The clipping element(s) or area that collision will be checked relative to.

{@link https://floating-ui.com/docs/detectOverflow#boundary}

collisionPadding 
Padding

The virtual padding around the boundary to check for collision.

{@link https://floating-ui.com/docs/detectOverflow#padding}

noShift 
boolean

When true, the Floating element won't be shifted if collisions occur.

{@link https://floating-ui.com/docs/shift}

noFlip 
boolean

When true, the placement of the Floating element won't change if collisions occur.

{@link https://floating-ui.com/docs/flip}

prioritizePlacement 
boolean

Whether to prioritize shifting (i.e. keeping original placement) over flipping when collisions occur.

{@link https://floating-ui.com/docs/flip#combining-with-shift}

arrow 
boolean

Whether to render arrow elements. The arrow has 2 parts: outer and inner. The inner will always overlap the outer to be able to create a continuous border connecting the arrow with the Floating element.

arrowPadding 
Padding

The padding between the arrow and the edges of the Floating element.

{@link https://floating-ui.com/docs/arrow#padding}

autoAvailableSize 
boolean

Whether to automatically set maxWidth and maxHeight of the Floating element to the available corresponding sizes.

matchAnchorSize 
boolean | "min" | "max"

Config to match the Anchor "size". The "size" here is detected by the final side of the Floating element:

  • If the side is vertical (i.e. top, bottom), Anchor "size" is width
  • If the side is vertical (i.e. left, right), Anchor "size" is height
transformOrigin 
boolean

Whether to add CSS transform-origin property equals to the exact position where the Floating element appears.

hideWhenDetached 
boolean

Whether to hide the Floating element when the Anchor element becomes fully occluded.

updatePositionStrategy 
"optimized" | "always" | "none"

Strategy to update the position of the Floating element when necessary (optimized) or on every frame (always) or never update at all (none).

{@link https://floating-ui.com/docs/autoupdate}

trapFocus 
boolean

Whether to trap focus so it cannot escape the Floating element via keyboard, pointer, or a programmatic focus.

autoFocus 
boolean

Whether to automatically focus first focusable element inside the Floating element on mount.

autoFocusElement 
string | true | FocusableElement | null

Custom element used to automatically focus on mount or when calling the exposed autoFocus() function. Can be:

  • true: to auto-focus the container
  • string: query selector to search for an element within the container
  • HTMLElement | SVGElement
floatingProps 
HTMLAttributes

Additional props bound to the Floating element.

contentClass 
HTMLAttributeClass

HTML class applied to the Content element.

contentStyle 
StyleValue

HTML style applied to the Content element.

contentProps 
HTMLAttributes

Additional props bound to the Content element.

trigger 
PopperTrigger
= "click"

The type of event to automatically control opening state of the Floating element.

open 
boolean

The opening state of the Floating element.

delay 
number | null

The delay duration (in milliseconds) from when hovering the Anchor element until the Popper gets opened.

NOTE:

  • If delay == 0, Popper will be opened instantly with no frame waited. If you want the behavior of setTimeout(() => { ...}, 0), set this prop to 1.

  • If delay == null, Popper will try getting the delay of the PopperHoverProvider context. If no context is provided, it will be 0.

disableHoverableContent 
boolean

When true, trying to hover the Floating element will close it.

forceHoverProviderSafeAreas 
boolean

By default, PopperSafeAreas provided by the parent (if exists) will override any Hover Provider. Setting this to true will force Hover Provider to override the parent instead.

floatingTeleportTo 
string | RendererElement | null

Specify target container. Can either be a selector or an actual element.

{@link https://vuejs.org/api/built-in-components.html#teleport}

floatingTeleportDisabled 
boolean

When true, the content will remain in its original location instead of moved into the target container. Can be changed dynamically.

{@link https://vuejs.org/api/built-in-components.html#teleport}

floatingTeleportDefer 
boolean

When true, the Teleport will defer until other parts of the application have been mounted before resolving its target. (3.5+)

{@link https://vuejs.org/api/built-in-components.html#teleport}

floatingClass 
HTMLAttributeClass

HTML class applied to the Floating element.

floatingStyle 
StyleValue

HTML style applied to the Floating element.

keyField 
string
= "key"
labelField 
string
= "label"
maxHeight 
string
= "none"

Events ​

NameParametersDescription
@select
[option: DropdownOption<any, string, string>]
@update:open
[opened: boolean]
@postOpen
[event: CustomEvent<any>]
@postClose
[event: CustomEvent<any>]
@pointerDownOutside
[event: PointerDownOutsideEvent]
@focusOutside
[event: FocusOutsideEvent]
@interactOutside
[event: PointerDownOutsideEvent | FocusOutsideEvent]
@keydownEscape
[event: KeyboardEvent]
@autoFocusOnMount
[event: CustomEvent<any>]
@autoFocusOnUnmount
[event: CustomEvent<any>]
@open
() => void
@close
(noForce?: boolean, immediate?: boolean) => void

Slots ​

NameScopedDescription
#default
{ open: boolean; onOpen: () => void; onClose: (force?: boolean | undefined, propagated?: boolean | undefined) => void; updatePosition: EventHookTrigger<void>; }

Exposed ​

NameTypeDescription
popperRefByKey
Partial<Record<PopperRefKey, { $: ComponentInternalInstance; $data: {}; $props: { readonly open?: boolean | undefined; readonly trigger: PopperTrigger; ... 46 more ...; readonly onAutoFocusOnUnmount?: ((event: CustomEvent<...>) => any) | undefined; } & VNodeProps & AllowedComponentProps & ComponentCustomProps; ... 1...
openedPopperRefKeys
Set<PopperRefKey>
updatePosition
() => Promise<void>