---
title: "MazTable"
description: "MazTable is designed to be a reusable data table with advanced features. Pagination, Search, Column Sorting, Row Selection, UI options, Loading and Slots."
package: "maz-ui"
url: "https://maz-ui.com/components/maz-table"
---

# MazTable

> MazTable is designed to be a reusable data table with advanced features. Pagination, Search, Column Sorting, Row Selection, UI options, Loading and Slots.

- Package: `maz-ui`
- Import: `import MazTable from 'maz-ui/components/MazTable'` or `import MazTableCell from 'maz-ui/components/MazTableCell'` or `import MazTableRow from 'maz-ui/components/MazTableRow'` or `import MazTableTitle from 'maz-ui/components/MazTableTitle'`
- Nuxt: auto-imported by `@maz-ui/nuxt`, no import needed in a Nuxt app
- Web: https://maz-ui.com/components/maz-table

> Before use it, you should install the MazUi plugin in your project, follow instructions in [Getting Started](../guide/getting-started.md)

## Key Features

1. Pagination (prop `pagination`)
   * The component supports pagination with buttons to go to the first, previous, next, and last page.
   * You can display only the pagination elements (input and buttons) and make API calls to your server to get elements by using the prop `pagination` with `no-paginate-rows`.
2. Search (prop `search`): It includes a search feature with a search bar where users can enter a query to filter displayed data. You can choose the column where the search will be activated. The search is a fuzzy search ([fuzzySearch](https://maz-ui.com/ecosystem/utils/fuzzy-search.md)): prefixes, words in any order, typos, accents and case, the rows keep their order.
3. Column Sorting (prop: `sortable`): Columns are sortable, indicated by arrow icons. Sorting can be activated by clicking on the column header.
4. Row Selection (prop `select-value="key"`): There is a dedicated column for selection with a checkbox for each row. Users can individually or collectively select/deselect rows.
5. Customizable Page Size: Users can choose the number of items to display per page using a dropdown list.
6. Loading Indicator (prop `loading`): A loading indicator (MazLoadingBar) is displayed when data is being loaded.
7. Animated rows (props `animated-rows` + `row-key`): rows slide to their new position when the order changes (FLIP animation). Respects `prefers-reduced-motion`.
8. Virtualization (prop `virtualized`): render only the rows visible in the viewport (plus an overscan) so the table stays fast with thousands of rows.

## Available models

* v-model: `(string | boolean | number)[] | undefined` (list of selected key)
* v-model:search-query: `string | undefined`
* v-model:page: `number`
* v-model:page-size: `number`

## Basic usage

You can use MazTable and his child component to build a simple table and enjoy the style.

```vue
<template>
  <MazTable size="sm" :headers="['#', 'Lastname', 'Firstname', 'Age']">
    <MazTableRow>
      <MazTableCell>
        1
      </MazTableCell>
      <MazTableCell>
        John
      </MazTableCell>
      <MazTableCell>
        Doe
      </MazTableCell>
      <MazTableCell>
        99
      </MazTableCell>
    </MazTableRow>
    <MazTableRow>
      <MazTableCell>
        2
      </MazTableCell>
      <MazTableCell>
        Doe
      </MazTableCell>
      <MazTableCell>
        John
      </MazTableCell>
      <MazTableCell>
        30
      </MazTableCell>
    </MazTableRow>
  </MazTable>
</template>

<script lang="ts" setup>
  import { MazTable, MazTableRow, MazTableCell } from 'maz-ui/components'
</script>
```

## Advanced data table

You can also provide all your data, the table is auto-generated and you can use the features listed on top

---

```vue
<template>
  <MazTable
    size="sm"
    v-model="selectedIds"
    v-model:search-query="searchQuery"
    v-model:page="page"
    v-model:page-size="pageSize"
    search
    pagination
    color="secondary"
    sortable
    selectable
    hoverable
    background-even
    selected-key="id"
    :headers="[
      { label:'#', key: 'index', align: 'center', width: '2rem', sortable: false },
      { label:'Name', key: 'name' },
      { label: 'Code', key: 'code', align: 'center'  },
      { label: 'Type', key: 'type' },
      { label: 'Area', key: 'areaName', align: 'center', classes: 'font-bold' },
    ]"
    :rows="competitions"
  >
    <template #cell-index="{ value }">
      <span class="text-base">{{value}}</span>
    </template>
    <template #cell-name="{ row, value }">
      <div class="flex items-center gap-2">
        <MazAvatar :src="row.logoUrl" size="0.5rem"></MazAvatar>
        <span>{{value}}</span>
      </div>
    </template>
    <template #cell-type="{ value }">
      <MazBadge :color="value === 'CUP' ? 'primary' : 'secondary'">{{value}}</MazBadge>
    </template>

    <template #actions>
      <MazBtn fab size="xs" color="destructive" icon="/trash.svg" />
    </template>
  </MazTable>
</template>

<script lang="ts" setup>
  import MazTable from 'maz-ui/components/MazTable'

  const competitions = [
  {
    id: '0262672d-7c7a-4d30-866e-edb88b5a5336',
    name: 'UEFA Champions League',
    code: 'CL',
    type: 'CUP',
    areaName: 'Europe',
    matchday: 6,
    logoUrl: 'https://crests.football-data.org/CL.png',
    groups: 1,
    index: 1,
  },
  {
    id: '08d15e97-a319-4772-9b82-f1877369b40f',
    name: 'Premier League',
    code: 'PL',
    type: 'LEAGUE',
    areaName: 'England',
    matchday: 18,
    logoUrl: 'https://crests.football-data.org/PL.png',
    groups: 1,
    index: 2,
  },
  {
    id: '17e62396-bbcb-42f5-acff-caed11534976',
    name: 'Serie A',
    code: 'SA',
    type: 'LEAGUE',
    areaName: 'Italy',
    matchday: 17,
    logoUrl: 'https://crests.football-data.org/SA.png',
    groups: 0,
    index: 3,
  },
  {
    id: '3726264e-ba3a-4a9f-b4a4-8fc33e12747c',
    name: 'FIFA World Cup',
    code: 'WC',
    type: 'CUP',
    areaName: 'World',
    matchday: 8,
    logoUrl: 'https://crests.football-data.org/qatar.png',
    groups: 1,
    index: 4,
  },
  {
    id: '555dc3f4-e592-46af-b634-59f07a201f2e',
    name: 'Primeira Liga',
    code: 'PPL',
    type: 'LEAGUE',
    areaName: 'Portugal',
    matchday: 15,
    logoUrl: 'https://crests.football-data.org/PPL.png',
    groups: 0,
    index: 5,
  },
  {
    id: '59bbdfa0-86d8-4a74-b701-435747c55a42',
    name: 'Primera Division',
    code: 'PD',
    type: 'LEAGUE',
    areaName: 'Spain',
    matchday: 18,
    logoUrl: 'https://crests.football-data.org/PD.png',
    groups: 1,
    index: 6,
  },
  {
    id: '6ae53332-3d27-4781-912d-d9c4e69657f9',
    name: 'Ligue 1',
    code: 'FL1',
    type: 'LEAGUE',
    areaName: 'France',
    matchday: 17,
    logoUrl: 'https://crests.football-data.org/FL1.png',
    groups: 4,
    index: 7,
  },
  {
    id: '747c79ee-89c8-436a-b0ea-53f05f180007',
    name: 'European Championship',
    code: 'EC',
    type: 'CUP',
    areaName: 'Europe',
    matchday: 1,
    logoUrl: 'https://crests.football-data.org/EUR.svg',
    groups: 1,
    index: 8,
  },
  {
    id: '7a32d897-6b22-4212-8ffe-049ae912c346',
    name: 'Eredivisie',
    code: 'DED',
    type: 'LEAGUE',
    areaName: 'Netherlands',
    matchday: 18,
    logoUrl: 'https://crests.football-data.org/ED.png',
    groups: 0,
    index: 9,
  },
  {
    id: 'ab57e2dc-272c-45e6-b13e-57617a13b753',
    name: 'Championship',
    code: 'ELC',
    type: 'LEAGUE',
    areaName: 'England',
    matchday: 23,
    logoUrl: 'https://crests.football-data.org/ELC.png',
    groups: 0,
    index: 10,
  },
  {
    id: 'b84e3295-7315-46c7-b979-6d9d784e5460',
    name: 'Campeonato Brasileiro Série A',
    code: 'BSA',
    type: 'LEAGUE',
    areaName: 'Brazil',
    matchday: 38,
    logoUrl: 'https://crests.football-data.org/764.svg',
    groups: 0,
    index: 11,
  },
  {
    id: 'cafad3ce-1783-4652-9248-4bcad024dd98',
    name: 'Copa Libertadores',
    code: 'CLI',
    type: 'CUP',
    areaName: 'South America',
    matchday: 11,
    logoUrl: 'https://crests.football-data.org/CLI.svg',
    groups: 0,
    index: 12,
  },
  {
    id: 'ed945bea-9a58-450a-8d62-7baa7722b5e7',
    name: 'Bundesliga',
    code: 'BL1',
    type: 'LEAGUE',
    areaName: 'Germany',
    matchday: 16,
    logoUrl: 'https://crests.football-data.org/BL1.png',
    groups: 0,
    index: 13,
  },
]
</script>
```

## Animated rows

Enable `animated-rows` to make rows slide to their new position when the order changes (FLIP animation) - perfect for live leaderboards or sortable lists. Provide a stable `row-key` (a field uniquely identifying each row) so every row keeps its identity across reorders. The animation is automatically disabled when the user prefers reduced motion.

```vue
<template>
  <MazBtn @click="shuffleRows">
    Shuffle
  </MazBtn>
  <MazTable
    animated-rows
    row-key="id"
    :headers="[
      { label: '#', key: 'id', align: 'center', width: '3rem' },
      { label: 'Name', key: 'name' },
      { label: 'Score', key: 'score', align: 'center' },
    ]"
    :rows="players"
  />
</template>

<script lang="ts" setup>
  import { MazTable } from 'maz-ui/components'
  import { ref } from 'vue'

  const players = ref([
    { id: 1, name: 'John', score: 12 },
    { id: 2, name: 'Jane', score: 24 },
    { id: 3, name: 'Alice', score: 8 },
    { id: 4, name: 'Bob', score: 31 },
  ])

  function shuffleRows() {
    players.value = [...players.value].sort(() => Math.random() - 0.5)
  }
</script>
```

## Virtualization

Enable `virtualized` to render only the rows inside the viewport (plus an overscan) instead of every row. This keeps the table fast and the DOM light even with tens of thousands of rows. It works in `rows` mode (data-driven), and `@tanstack/vue-virtual` is loaded on demand - pages that never virtualize a table never ship it.

The example below renders **10 000 rows** but only keeps ~20 `<tr>` in the DOM at any time.

```vue
<template>
  <MazTable
    virtualized
    max-height="400px"
    :estimated-row-height="38"
    :headers="[
      { label: '#', key: 'id', width: '5rem' },
      { label: 'Name', key: 'name', width: '12rem' },
      { label: 'Email', key: 'email' },
      { label: 'Score', key: 'score', align: 'center', width: '6rem' },
    ]"
    :rows="rows"
  />
</template>

<script lang="ts" setup>
  import { MazTable } from 'maz-ui/components'

  // 10 000 rows - only the visible window is rendered to the DOM
  const rows = Array.from({ length: 10_000 }, (_, i) => ({
    id: i + 1,
    name: `User ${i + 1}`,
    email: `user${i + 1}@maz-ui.com`,
    score: Math.round(Math.random() * 100),
  }))
</script>
```

### Options

| Prop | Default | Description |
| --- | --- | --- |
| `virtualized` | `false` | Turns virtualization on. |
| `max-height` | - | **Required.** Bounds the scroll viewport (any CSS length, e.g. `'400px'`, `'70vh'`). Scrolling is enabled automatically and the header stays sticky. |
| `estimated-row-height` | `44` | Fixed row height (in px) used to place rows and size the spacers. Set it to your real row height; virtualized rows should be uniform (single line). |
| `overscan` | `10` | Rows rendered outside the viewport on each side. |

### Good to know

* **Set a `width` (or `minWidth`) on your headers.** Virtualization forces `table-layout: fixed` so columns stay aligned across the rendered window; without widths the browser distributes them equally.
* **Accessibility:** the table exposes `aria-rowcount` and each rendered row an `aria-rowindex`, so screen readers still announce "row X of N".
* **Ignored** (with a dev warning) when `animated-rows` is enabled or when you provide a custom default slot - those paths render every row.
* **Rendered client-side:** the virtualized body is empty during SSR and fills in on hydration.

## Loading

Enable the loading state with the prop `loading`

```html{2}
<MazTable
  :loading="true"
  :headers="['#', 'Lastname', 'Firstname', 'Age']"
>
  ...
</MazTable>
```

## Sizing

Available sizes: `'mini' | 'xs' | 'sm' | 'md' | 'lg' | 'xl'`

```html
<MazTable size="xs" :headers="['#', 'Lastname', 'Firstname', 'Age']">
  ...
</MazTable>
<MazTable size="md" :headers="['#', 'Lastname', 'Firstname', 'Age']">
  ...
</MazTable>
<MazTable size="lg" :headers="['#', 'Lastname', 'Firstname', 'Age']">
  ...
</MazTable>
```

```ts
type Row =  Record<string, any> & {
  selected?: boolean
  action?: (row: Row) => unknown
  classes?: HTMLAttributes['class']
}
```

```ts
export interface MazTableHeadersEnriched {
  label: string
  key?: string
  sortable?: boolean
  hidden?: boolean
  srOnly?: boolean
  width?: string
  maxWidth?: string
  minWidth?: string
  classes?: ThHTMLAttributes['class']
  scope?: ThHTMLAttributes['scope']
  align?: ThHTMLAttributes['align']
  rowspan?: ThHTMLAttributes['rowspan']
  colspan?: ThHTMLAttributes['colspan']
  headers?: ThHTMLAttributes['headers']
}
```
