Dropdown

Helper required

This component requires a helper. Make sure to read the documentation carefully so you know how to use it.

A dropdown component that takes care of all the annoying bits for you, with added support for programmatic triggers on top.

Usage

'Read the “', Usage, '” section'

Preview

Trigger Dropdown

• Option 1
• Option 2

Code

DropdownExample.astro

---
import { Dropdown, Button } from 'studiocms:ui/components';
---

<Dropdown
  id='dropdown'
  options={[
    { label: 'Option 1', value: 'opt-1'},
    { label: 'Option 2', value: 'opt-2'},
  ]}
>
  <Button color='primary'>
    Trigger Dropdown
  </Button>
</Dropdown>

Script Tag

import { DropdownHelper } from 'studiocms:ui/components';

const dropdown = new DropdownHelper('dropdown');

Dropdown Position

'Read the “', Dropdown Position, '” section'

You can change the dropdowns position by supplying the align prop.

Preview

Start-aligned

• Option 1
• Option 2

Center-aligned

• Option 1
• Option 2

End-aligned

• Option 1
• Option 2

Code

DropdownAlignStartExample.astro

---
import { Dropdown, Button } from 'studiocms:ui/components';
---

<Dropdown
  id='dropdown'
  options={[
    { label: 'Option 1', value: 'opt-1'},
    { label: 'Option 2', value: 'opt-2'},
  ]}
  align='start'
>
  <Button color='primary'>
    Start-aligned
  </Button>
</Dropdown>

<!-- Other buttons omitted for simplicity -->

Script Tag

import { DropdownHelper } from 'studiocms:ui/components';

const dropdown = new DropdownHelper('dropdown');

Right-Click Triggering

'Read the “', Right-Click Triggering, '” section'

You can tell the dropdown wrapper to only show the dropdown when it’s children are right-clicked:

Preview

Right Click

• Option 1
• Option 2

Code

DropdownRightClickExample.astro

---
import { Dropdown, Button } from 'studiocms:ui/components';
---

<Dropdown
  id='dropdown'
  options={[
    { label: 'Option 1', value: 'opt-1'},
    { label: 'Option 2', value: 'opt-2'},
  ]}
  triggerOn='right'
>
  <Button color='primary'>
    Right Click
  </Button>
</Dropdown>

Script Tag

import { DropdownHelper } from 'studiocms:ui/components';

const dropdown = new DropdownHelper('dropdown');

Note

You can also tell the dropdown to trigger on both left- & right-click by using the triggerOn='both' prop.

Disabled

'Read the “', Disabled, '” section'

You can disable a dropdown by passing the disabled prop.

DropdownDisabledExample.astro

<Dropdown disabled {/* ... */}>
  <!-- ... -->
</Dropdown>

Option Options

'Read the “', Option Options, '” section'

No, you read that right. You can customize the options too. You can individually disable them, turn them into links and also change their color to any of the default colors:

Preview

Customized Options

• Default
• Primary
• Success
• Warning
• Danger
• Info
• Monochrome
• Disabled
• As Link

Code

DropdownOptionsExample.astro

---
import { Dropdown, Button } from 'studiocms:ui/components';
---

<Dropdown
  id='dropdown'
  options={[
    { label: 'Default', value: 'default', color: 'default' },
    { label: 'Primary', value: 'primary', color: 'primary' },
    { label: 'Success', value: 'success', color: 'success' },
    { label: 'Warning', value: 'warning', color: 'warning' },
    { label: 'Danger', value: 'danger', color: 'danger' },
    { label: 'Info', value: 'info', color: 'info' },
    { label: 'Monochrome', value: 'mono', color: 'mono' },
    { label: 'Disabled', value: 'disabled', disabled: true },
    { label: 'As Link', value: 'custom-href', href: '/' },
  ]}
>
  <Button color='primary'>
    Customized Options
  </Button>
</Dropdown>

Script Tag

import { DropdownHelper } from 'studiocms:ui/components';

const dropdown = new DropdownHelper('dropdown');

Icons

'Read the “', Icons, '” section'

The dropdown items also support icons. You can pass an icon name to the option object:

Preview

Customized Icons

• Notifications
• Settings
• Profile

Code

DropdownIconsExample.astro

---
import { Dropdown, Button } from 'studiocms:ui/components';
---

<Dropdown
  id='dropdown'
  options={[
    { label: 'Notifications', value: 'notifications', icon: 'bell' },
    { label: 'Settings', value: 'settings', icon: 'cog-6-tooth' },
    { label: 'Profile', value: 'profile', icon: 'user' },
  ]}
>
  <Button color='primary'>
    Customized Icons
  </Button>
</Dropdown>

Script Tag

import { DropdownHelper } from 'studiocms:ui/components';

const dropdown = new DropdownHelper('dropdown');

Controlling Dropdowns Programmatically

'Read the “', Controlling Dropdowns Programmatically, '” section'

You know how, this entire page, we’ve been assigning our DropdownHelper to a variable? There’s a reason for that. The DropdownHelper allows you to access some built-in functions for programmatically toggling, showing and hiding the dropdown. You can even register a callback for when one of the dropdowns options has been clicked!

Script Tag

import { DropdownHelper } from 'studiocms:ui/components';

const dropdown = new DropdownHelper('dropdown');

dropdown.registerClickCallback((value) => {
  // `value` will be the value you gave your option in the dropdown wrapper.
  console.log(value);
});

// You can toggle the dropdown like this:
dropdown.toggle();

// Instead of toggling, you can simply show or hide the dropdown:
dropdown.show();
dropdown.hide();