Skip to content
DocX

UIToolbar

UIToolbar

A versatile toolbar component that provides a container for actions, filters, search, and other controls commonly used in application headers and data views.

<template>
  <UIToolbar
    :title="'Products'"
    :description="'Manage your product catalog'"
    :actions="actions"
    :search="searchConfig"
    :filter="filterConfig"
    :sort="sortConfig"
    :pagination="paginationConfig"
  >
    <template #actions>
      <UIButton
        type="primary"
        @click="createProduct"
      >
        <PlusIcon class="w-5 h-5 mr-2" />
        Add Product
      </UIButton>
    </template>


    <template #filter>
      <UIFilterDropdown
        v-model="filters"
        :options="filterOptions"
      />
    </template>
  </UIToolbar>
</template>


<script setup lang="ts">
const searchConfig = {
  placeholder: 'Search products...',
  debounce: 300
}


const filterConfig = {
  show: true,
  placement: 'left'
}


const sortConfig = {
  options: [
    { label: 'Name', value: 'name' },
    { label: 'Price', value: 'price' },
    { label: 'Created', value: 'created_at' }
  ]
}


const paginationConfig = {
  total: 100,
  pageSize: 10,
  current: 1
}
</script>

Props

  • title (string): Toolbar title
  • description (string): Toolbar description
  • actions (array): Action buttons configuration
  • search (object): Search configuration
  • filter (object): Filter configuration
  • sort (object): Sort configuration
  • pagination (object): Pagination configuration
  • loading (boolean): Loading state
  • sticky (boolean): Sticky positioning
  • bordered (boolean): Show border
  • compact (boolean): Compact layout
  • showDivider (boolean): Show divider between sections

Events

  • search: Search query changed
  • filter: Filters changed
  • sort: Sort changed
  • page-change: Page changed
  • action: Action clicked

Slots

  • title: Custom title content
  • description: Custom description content
  • actions: Custom actions content
  • search: Custom search content
  • filter: Custom filter content
  • sort: Custom sort content
  • pagination: Custom pagination content

Usage Examples

  1. Basic Toolbar:
<template>
  <UIToolbar
    title="Documents"
    description="All your files and folders"
  >
    <template #actions>
      <UIButton
        type="primary"
        @click="uploadFile"
      >
        Upload
      </UIButton>
    </template>
  </UIToolbar>
</template>
  1. Data Table Toolbar:
<template>
  <div class="space-y-4">
    <UIToolbar
      :title="'Users'"
      :loading="loading"
      :sticky="true"
    >
      <template #search>
        <UISearch
          v-model="searchQuery"
          placeholder="Search users..."
          :debounce="300"
          @search="handleSearch"
        />
      </template>


      <template #filter>
        <div class="flex items-center space-x-4">
          <UISelect
            v-model="filters.role"
            :options="roleOptions"
            placeholder="Role"
          />


          <UISelect
            v-model="filters.status"
            :options="statusOptions"
            placeholder="Status"
          />


          <UIDatePicker
            v-model="filters.dateRange"
            type="range"
            placeholder="Date range"
          />
        </div>
      </template>


      <template #actions>
        <div class="flex items-center space-x-2">
          <UIButton
            v-if="selectedRows.length"
            variant="error"
            @click="deleteSelected"
          >
            Delete Selected
          </UIButton>


          <UIButton
            type="primary"
            @click="createUser"
          >
            Add User
          </UIButton>
        </div>
      </template>
    </UIToolbar>


    <UITable
      :data="users"
      :columns="columns"
      :loading="loading"
    />
  </div>
</template>
  1. Complex Toolbar:
<template>
  <UIToolbar
    :title="viewTitle"
    :bordered="true"
    class="bg-white"
  >
    <template #title>
      <div class="flex items-center space-x-4">
        <UISegmentedControl
          v-model="currentView"
          :options="viewOptions"
        />


        <UIBadge
          :variant="getStatusVariant(status)"
          size="sm"
        >
          {{ status }}
        </UIBadge>
      </div>
    </template>


    <template #search>
      <UISearch
        v-model="searchQuery"
        :placeholder="searchPlaceholder"
        class="w-80"
      >
        <template #prefix>
          <UISelect
            v-model="searchType"
            :options="searchTypes"
            size="sm"
            class="w-32"
          />
        </template>
      </UISearch>
    </template>


    <template #filter>
      <UISortFilter
        v-model:sort="sortConfig"
        v-model:filter="filterConfig"
        :sortOptions="sortOptions"
        :filterOptions="filterOptions"
        @apply="applyFilters"
      />
    </template>


    <template #actions>
      <div class="flex items-center space-x-2">
        <UIButton
          variant="outline"
          @click="exportData"
        >
          <DownloadIcon class="w-5 h-5 mr-2" />
          Export
        </UIButton>


        <UIPopover placement="bottom-end">
          <template #trigger>
            <UIButton type="primary">
              Actions
              <ChevronDownIcon class="w-5 h-5 ml-2" />
            </UIButton>
          </template>


          <div class="py-1">
            <UIButton
              v-for="action in actions"
              :key="action.id"
              variant="ghost"
              class="w-full justify-start"
              @click="action.handler"
            >
              <component
                :is="action.icon"
                class="w-5 h-5 mr-2"
              />
              {{ action.label }}
            </UIButton>
          </div>
        </UIPopover>
      </div>
    </template>
  </UIToolbar>
</template>

Best Practices

  1. Layout:

    • Consistent spacing
    • Clear hierarchy
    • Responsive design
    • Mobile optimization

  2. User Experience:

    • Quick access to actions
    • Clear feedback
    • Efficient workflows
    • Contextual controls

  3. Accessibility:

    • ARIA labels
    • Keyboard navigation
    • Focus management
    • Screen reader support

  4. Performance:

    • Efficient updates
    • Debounced search
    • Optimized rendering
    • Memory management

Common Use Cases

  1. List View Header:
<template>
  <div class="space-y-4">
    <UIToolbar
      :title="listTitle"
      :description="listDescription"
      :sticky="true"
      class="bg-white border-b"
    >
      <template #search>
        <UISearch
          v-model="search"
          :placeholder="searchPlaceholder"
        />
      </template>


      <template #filter>
        <UISelect
          v-model="viewType"
          :options="viewTypes"
          class="w-40"
        />
      </template>


      <template #actions>
        <UIButton
          type="primary"
          @click="createItem"
        >
          Create New
        </UIButton>
      </template>
    </UIToolbar>


    <component
      :is="currentViewComponent"
      :items="filteredItems"
      :loading="loading"
    />
  </div>
</template>
  1. Data Grid Toolbar:
<template>
  <UIToolbar
    :loading="loading"
    :sticky="true"
  >
    <template #title>
      <div class="flex items-center space-x-2">
        <h2 class="text-lg font-medium">
          {{ totalItems }} Items
        </h2>
        <UIBadge
          v-if="selectedItems.length"
          variant="primary"
        >
          {{ selectedItems.length }} selected
        </UIBadge>
      </div>
    </template>


    <template #filter>
      <div class="flex items-center space-x-4">
        <UIFilterDropdown
          v-model="filters"
          :options="filterOptions"
        />


        <UISortFilter
          v-model="sortConfig"
          :options="sortOptions"
        />
      </div>
    </template>


    <template #actions>
      <BulkActions
        :selected="selectedItems"
        @action="handleBulkAction"
      />
    </template>


    <template #pagination>
      <UIPagination
        v-model="page"
        :total="totalPages"
        :loading="loading"
      />
    </template>
  </UIToolbar>
</template>
  1. Mobile Toolbar:
<template>
  <UIToolbar
    :compact="true"
    class="lg:hidden"
  >
    <template #title>
      <UIButton
        variant="ghost"
        class="lg:hidden"
        @click="toggleSidebar"
      >
        <MenuIcon class="w-5 h-5" />
      </UIButton>
    </template>


    <template #actions>
      <div class="flex items-center space-x-2">
        <UIButton
          variant="ghost"
          @click="showSearch"
        >
          <SearchIcon class="w-5 h-5" />
        </UIButton>


        <UIButton
          variant="ghost"
          @click="showFilters"
        >
          <FilterIcon class="w-5 h-5" />
        </UIButton>


        <UIButton
          type="primary"
          class="!p-2"
        >
          <PlusIcon class="w-5 h-5" />
        </UIButton>
      </div>
    </template>
  </UIToolbar>


  <UIDrawer
    v-model:show="showSearchDrawer"
    placement="top"
  >
    <UISearch
      v-model="search"
      placeholder="Search..."
      class="w-full"
      autofocus
    />
  </UIDrawer>


  <UIDrawer
    v-model:show="showFiltersDrawer"
    placement="right"
  >
    <FilterPanel
      v-model="filters"
      @apply="applyFilters"
      @reset="resetFilters"
    />
  </UIDrawer>
</template>

Component Composition

The UIToolbar component works well with:

  • UIButton for actions
  • UISearch for search functionality
  • UISelect for filtering
  • UIFilterDropdown for complex filters
  • UISortFilter for sorting
  • UIPagination for pagination
  • UIBadge for status/counts
  • UIDrawer for mobile views