The Dropdown component offers a flexible and customizable way to display a list of links or actions in a compact, toggle-able menu. It's perfect for navigation menus, settings, or any context where you want to provide users with multiple options in a clean, organized format.
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.
<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.
<!-- 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 (you can set custom styles) -->
<Dropdown size="custom"> ... </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.
<!-- 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".
<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.
<!-- 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.
<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.
<Dropdown label="Dropdown">
<DropdownItem url="/"></DropdownItem> Link>
<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.
<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.
<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
The animate prop lets you control the speed of the dropdown's animation. You can choose from various options like slower for a very slow animation, slow for a slightly slower effect, medium for the default speed, fast for quicker animations, and faster for the fastest effect. If you prefer to disable the animation altogether, you can set the prop to false.
- 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.
<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
<Dropdown animate="slower"> ... </Dropdown>
<Dropdown animate="slow"> ... </Dropdown>
<Dropdown animate="medium"> ... </Dropdown>
<Dropdown animation="fast"> ... </Dropdown>
<Dropdown animation="faster"> ... </Dropdown>
<Dropdown animation={false}> ... </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.
<!-- 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.
<!-- 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.
<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.