Icons
A picture is worth a thousand words. An icon, about one. Use Lucide or any other set, sized and coloured by the component it sits in.
Lucide
Components draw their icons from Lucide, through the @lucide/vue package. Components that show an icon of their own, such as the check in a select or the chevron of a submenu, list it as a dependency, so the CLI installs it with them. Using Lucide in your own code? Add it once:
pnpm add @lucide/vue
Each icon is a component named after it in PascalCase. Import only the ones you use, and the rest stay out of your bundle:
<script setup lang="ts">
import { Mail, Trash2 } from '@lucide/vue'
</script>
<template>
<Mail />
<Trash2 class="size-5 text-destructive" />
</template>
Lucide marks its icons aria-hidden: next to a label, an icon adds nothing for a screen reader. An icon on its own, as in an icon button, needs a name on the element around it: aria-label on the button.
Size and colour
Icons take their size from the component they sit in. Buttons, menu items, select options and similar parts size an icon without a size-* class of its own from the control scale: 16px at the default size, 14px at xs, 20px at lg and xl. Icons draw in currentColor, so they follow the text: muted in a menu item, --destructive in a destructive one. A size-* or text-* class on the icon overrides either.
Want every icon in a part bigger? icon-size-* sizes every svg inside an element that has no size-* class of its own. It takes the spacing scale, a length or a variable, and in class it replaces the component's own size:
<Button class="icon-size-5">
<Plus data-icon="inline-start" />
New project
</Button>
<span class="icon-size-(--my-icon) [--my-icon:18px]"><Mail /></span>
In a button, mark an icon next to the label with data-icon="inline-start" or data-icon="inline-end", and the button tightens its padding on that side:
<Button>
<Plus data-icon="inline-start" />
New project
</Button>
Replacing a component's icon
Where a component draws its own icon, a slot or a prop swaps it without editing the component:
| Component | Icon | Swap it with |
|---|---|---|
| Accordion | Chevron in AccordionTrigger | icon slot |
| Breadcrumb | Chevron in BreadcrumbSeparator, dots in BreadcrumbEllipsis | Default slot |
| Calendar, RangeCalendar | Chevrons in the Previous and Next arrows | prev-icon and next-icon slots, or the default slot of CalendarPrevButton and CalendarNextButton |
| ColorPicker | Check on the selected ColorPickerSwatch | Default slot |
| Combobox | Chevron in ComboboxTrigger, X in ComboboxCancel | Default slot |
| DatePicker, DateRangePicker | Calendar in DatePickerTrigger | Default slot |
| Select, Combobox, Listbox | Check on the selected item | indicator-icon slot |
| Menu, Menubar, DrawerMenu | Check and dot on checkbox and radio items | indicator-icon slot |
| Select | Chevrons in SelectScrollUpButton and SelectScrollDownButton | Default slot |
| Tree | Chevron in TreeItemToggle, a spinner while a node loads | TreeItemToggle's default slot for the chevron, the item slot for both |
| InputNumber | Minus and plus in InputNumberDecrement and InputNumberIncrement, chevrons when vertical | Default slot |
| NavigationMenu | Chevron in NavigationMenuTrigger, arrow in NavigationMenuIndicator | icon slot on the trigger, default slot on the indicator |
| Pagination | Chevrons in PaginationPrevious and PaginationNext, dots in PaginationEllipsis | Default slot; Previous and Next take the label with it |
| PinInput | Dash in PinInputSeparator | Default slot |
| TagsInput | X in TagsInputItemDelete | Default slot |
| FileUpload | Upload arrow in the zone or the button, file icon on files without a thumbnail, X on Remove | icon prop (false for none) or leading slot; file-icon prop or file-leading slot; file-trailing slot for Remove |
| Splitter | Grip in SplitterHandle | Default slot |
| Image | Broken image in ImageError | Default slot |
| Switch | None | checked-icon and unchecked-icon slots |
| Rating | Star, empty and filled | icon slot, which gets filled; empty-icon slot for the empty one only |
| Toast | One per colour, none for neutral | icon option, false for none |
| Dialog, Drawer | X in the close button | :show-close-button="false", then a button of your own in DialogClose or DrawerClose |
A few icons have no slot: the chevron of SelectTrigger, the submenu chevrons and DrawerMenu's back arrow, the search icon in CommandInput, and DataTable's sort and expand icons. Change those in the component's source. That's also how you swap an icon everywhere at once: it's your code.
Another icon set
Nothing depends on Lucide beyond those imports. Any Vue component that renders an <svg>, such as Iconify through @iconify/vue or unplugin-icons, fits the same places and picks up the same size and colour.
Two icons aren't icons at all. The check in a checkbox draws itself in as the box is ticked, and the spinner's arc grows and shrinks as it turns. The components draw both, since a static icon can't move like that.