Dropdown

About

The Dropdown component allows you to create a menu that can be expanded or collapsed by clicking or hovering over a trigger element. It supports various customization options such as alignment, animation styles, animation speeds, and trigger events. Each item within the Dropdown can be linked to different actions or URLs, making it a versatile tool for enhancing user interaction in your application.

Example

To use the Dropdown component in your project, you first need to import it along with the DropdownItem component. Here's how you can set up the Dropdown in your Svelte component.

Here’s a simple example of how to implement the Dropdown component. It includes a label and multiple DropdownItem components, which represent the individual links or actions within the dropdown.

Svelte

<script>
  import { Dropdown, DropdownItem } from "theui-svelte";
</script>

<Dropdown label="Dropdown">
  <DropdownItem url="/">Link 1</DropdownItem>
  <DropdownItem url="/">Link 2</DropdownItem>
  <DropdownItem url="/">Link 3</DropdownItem>
</Dropdown>

In this example, the Dropdown is triggered by a label ("Dropdown"), and it contains three items, each with a URL and text.

Dropdown Sizing

The width of the Dropdown component can be customized using the width prop. You can choose from predefined sizes or set a custom width to suit your design needs. Here's a breakdown of the available options:

auto: The Dropdown will automatically adjust its size based on its content.
sm: A small size for compact dropdowns.
md: The default medium size for a standard dropdown.
lg: A large size for more prominent dropdowns.
full: The dropdown will take up the full width of its container.
custom: Use this option when you want to set a custom size for the dropdown through additional styling.

Svelte

<!-- Automatically adjusts the size based on content -->
<Dropdown size="auto"> ... </Dropdown>

<!-- Small dropdown -->
<Dropdown size="sm"> ... </Dropdown>

<!-- Default medium size dropdown -->
<Dropdown size="md"> ... </Dropdown>

<!-- Large dropdown -->
<Dropdown size="lg"> ... </Dropdown>

<!-- Full-width dropdown -->
<Dropdown size="full"> ... </Dropdown>

<!-- Custom size dropdown - set custom width using TailwindCSS class -->
<Dropdown size="custom" dropdownClasses="w-[300px]"> ... </Dropdown>

In these examples, the size prop allows you to quickly adjust the appearance of the dropdown to fit different design needs.

Alignment

The align prop in the Dropdown component controls the alignment of the dropdown menu relative to its trigger. You can choose between two options:

start: Aligns the dropdown to the start (left) of the trigger element.
end: Aligns the dropdown to the end (right) of the trigger element. This is the default alignment.

Svelte

<!-- Align dropdown to the start (left) of the trigger -->
<Dropdown align="start"> ... </Dropdown>

<!-- Default alignment (align to the right of the trigger) -->
<Dropdown align="end"> ... </Dropdown>

Dropdown Trigger Event

The dropdownEvent prop defines how the dropdown is triggered. By default, the dropdown opens when clicked, but you can change this behavior to trigger on hover by setting it to "hover".

Svelte

<Dropdown dropdownEvent="click"> ... </Dropdown> <!-- Default -->
<Dropdown dropdownEvent="hover"> ... </Dropdown>

Custom Dropdown Trigger

The label prop allows you to set a custom label for the dropdown trigger. You can either use a text or HTML string or define a custom trigger element using the snippet block.

label as props: Directly set the trigger label as a prop.
label as snippet: Define a custom trigger with any HTML or component structure.

Svelte

<!-- Dropdown label by prop -->
<Dropdown label="Dropdown text label"> ... </Dropdown>

<!-- Custom dropdown label by Snippet -->
<Dropdown>
  {#snippet label()}
    <span class="...">Dropdown snippet label</span>
  {/snippet}
</Dropdown>

Item Types

Link

The DropdownItem component supports four native types for consistent UI: link, button, header, and divider. The type of each item is controlled by the type prop, which defaults to link. The type prop can be set to 'link' | 'divider' | 'header' | 'button'.

link: The default type, renders a standard hyperlink.
button: Renders a clickable button within the dropdown.
header: Creates a non-clickable header to separate sections.
divider: Adds a visual divider to separate items.

You can also add custom items, but these four types are provided natively for a consistent UI experience.

Svelte

<Dropdown label="Dropdown">
  <!-- Header item -->
  <DropdownItem type="header">Section Header</DropdownItem>
  <!-- Link item (default) -->
  <DropdownItem url="/">Link 1</DropdownItem>
  <DropdownItem url="/">Link 2</DropdownItem>
  <!-- Divider item -->
  <DropdownItem type="divider" />
  <!-- Button item -->
  <DropdownItem type="button">Button 1</DropdownItem>
</Dropdown>

This setup ensures your dropdown maintains a uniform appearance and functionality across different types of items.

Active State

The active prop in the DropdownItem component is used to indicate whether the item is currently active. This prop accepts a boolean value and defaults to false. When set to true, the item will appear highlighted to show it is active.

Svelte

<Dropdown label="Dropdown">
  <DropdownItem url="/">Link</DropdownItem>
  <DropdownItem url="/" active={true}>Active Link</DropdownItem>
  <DropdownItem url="/">Link</DropdownItem>
</Dropdown>

Using the active prop helps visually distinguish the selected or currently active item within the dropdown.

Dropdown Item's Content

The DropdownItem component provides two snippet blocks, startItem and endItem, for adding custom content before or after the dropdown text.

startItem: Displays content before the dropdown text, ideal for icons, images, or similar elements.
endItem: Shows content after the dropdown text, perfect for badges, extra messages, or additional icons.

Svelte

<Dropdown label="Dropdown" size="md">
  <DropdownItem url="/">
    {#snippet startItem()}
      <Svg>
        <path d="M8 16a2 2 0 0 ... 13 6c0 .88.32 4.2 1.22 6"/>
      </Svg>
    {/snippet}
    Notification
  </DropdownItem>
  <DropdownItem url="/">
    Notification
    {#snippet endItem()}
      <Badge>New</Badge>
    {/snippet}
  </DropdownItem>
  <DropdownItem url="/">
    {#snippet startItem()}
      <Svg>
        <path d="M8 16a2 2 0 0 ... 13 6c0 .88.32 4.2 1.22 6"/>
      </Svg>
    {/snippet}
    Notification
    {#snippet endItem()}
      <Badge>New</Badge>
    {/snippet}
  </DropdownItem>
</Dropdown>

These snippet blocks provide flexibility to enhance the dropdown items with additional content while maintaining a clean and consistent design.

Custom Item

The DropdownItem component also supports fully custom content, allowing you to create items beyond the predefined types. By using custom markup within DropdownItem, you can design complex or unique dropdown items to fit your specific needs.

Svelte

<Dropdown label="Custom Dropdown" size="md">
  <DropdownItem url="/" class="hover:bg-brand-primary-500 ... flex-wrap">
    <div class="w-full text-start">
      <p class="font-bold">Svelte 5 Component</p>
      Kickstart your ... ecosystem.
    </div>
  </DropdownItem>
</Dropdown>

This approach offers full flexibility, enabling you to craft dropdown items with custom content and styling, perfect for tailored user interfaces.

Animation

Based on your design requirements, you can customize the animation type and the speed of the Dropdown using the animation and animationSpeed props.

Animation Type

The animation prop controls how the dropdown appears when opened. It supports multiple animation styles to enhance user experience. By default, the dropdown uses the slide-up animation. Adjust this prop to match your design preferences.

slide-left: The dropdown slides in from the left.
slide-up: The default animation, sliding in from the bottom.
slide-right: Slides in from the right.
slide-down: Slides in from the top.
fade: A smooth fade-in animation.
zoom-in: The dropdown zooms in from a smaller size.
zoom-out: The dropdown zooms out from a larger size.

Svelte

<Dropdown animation="slide-left"> ... </Dropdown>
<Dropdown animation="slide-up"> ... </Dropdown>  <!-- Default -->
<Dropdown animation="slide-right"> ... </Dropdown>
<Dropdown animation="slide-down"> ... </Dropdown>
<Dropdown animation="fade"> ... </Dropdown>
<Dropdown animation="zoom-in"> ... </Dropdown>
<Dropdown animation="zoom-out"> ... </Dropdown>

These animation options help create a more engaging and visually appealing dropdown experience.

Animation Speed

The animationSpeed prop controls the speed of the dropdown animation, allowing for smooth transitions at different paces. It accepts the following values none, slower, slow, normal, fast and faster

Svelte

<Dropdown animationSpeed="slower"> ... </Dropdown>
<Dropdown animationSpeed="slow"> ... </Dropdown>
<Dropdown animationSpeed="medium"> ... </Dropdown>
<Dropdown animationSpeed="fast"> ... </Dropdown>
<Dropdown animationSpeed="faster"> ... </Dropdown>
<Dropdown animationSpeed="none"> ... </Dropdown>

This allows you to tailor the dropdown's animation speed to fit your design needs and improve user interaction.

Dropdown Backdrop

The backdrop prop determines whether a backdrop is shown behind the dropdown. When set to true, a backdrop is displayed; by default, it is set to false, meaning no backdrop is shown.

Svelte

<!-- With backdrop -->
<Dropdown backdrop={true}> ... </Dropdown>

<!-- Without backdrop -->
<Dropdown backdrop={false}> ... </Dropdown>

Close on Outside Click

The closeOnBlur prop controls whether the dropdown closes when it loses focus. By default, it is set to true, meaning the dropdown will close when you click outside of it. Setting it to false will keep the dropdown open even when it loses focus.

Svelte

<!-- Keep the dropdown open on blur -->
<Dropdown closeOnBlur={false}> ... </Dropdown>

<!-- Default behavior: Close dropdown on blur -->
<Dropdown closeOnBlur={true}> ... </Dropdown>

Customization

The Dropdown component provides several props to customize the appearance of the dropdown items and container. These props allow you to apply custom classes for different elements, giving you full control over the styling.

containerClasses: Custom classes for the outer dropdown container.
dropdownClasses: Customizes the dropdown content area.
linkClasses: Sets custom classes for regular dropdown links.
activeLinkClasses: Applies custom classes to the active dropdown item.
dividerClasses: Customizes the appearance of divider items.
headerClasses: Adds custom styling to header items within the dropdown.

Svelte

<Dropdown
  label="Customized Dropdown"
  containerClasses="border-4 rounded-lg"
  dropdownClasses="shadow-lg bg-green-50"
  linkClasses="text-green-500 hover:bg-green-100"
  activeLinkClasses="text-white bg-green-500"
  dividerClasses="border-b-2 border-green-200"
  headerClasses="text-green-600 text-xs"
>
  <DropdownItem url="/">Link 1</DropdownItem>
  <DropdownItem type="header">Section Header</DropdownItem>
  <DropdownItem type="divider" />
  <DropdownItem url="/" active={true}>Link 2</DropdownItem>
</Dropdown>

These props enable you to tailor the dropdown's look and feel, ensuring it aligns with your design preferences and project requirements.

Accessibility

The Dropdown component follows WAI-ARIA best practices.

The trigger button uses aria-haspopup="menu", aria-expanded, and aria-controls to describe the dropdown behavior.
The dropdown list uses role="menu" with each item using appropriate roles:
- menuitem for clickable items
- heading for group labels
- presentation for dividers
Keyboard navigation is supported via arrow keys, Enter and Escape.

Getting Started

Components

Forms

Utilities

About

Example

Alignment

Item Types

Link

Active State

Custom Item

Animation

Animation Type

Animation Speed

Close on Outside Click

Customization

Accessibility

Configuration