Display data in a table format. ## Usage Use the `rows` prop to display data in a table. By default, all fields from the rows will be displayed.Props Prop Type Description checked Boolean Indicates if all rows are selected change Function Function to handle selection state changes. Must receive a boolean value (true/false) indeterminate Boolean Indicates partial selection (when some rows are selected) ```vue ``` ## Columns Configure displayed columns using the `columns` prop. Each column object can have these properties: - `label` - Header label (configurable via `column-attribute` prop) - `key` - Field to display from row data - `sortable` - Enable column sorting (defaults to `false`) - `direction` - Initial sort direction (defaults to `asc`) - `class` - CSS class for column cells - `rowClass` - CSS class for data cells - `sort` - Custom sort function (defaults to simple comparison) Arguments for the sort function are: Value A, Value B, Direction - 'asc' or 'desc' Example sort function: ```js (a, b, direction) => { if (!a || !b) return 0 const aPrice = parseInt(a.replace(/[,$]/g, "")) const bPrice = parseInt(b.replace(/[,$]/g, "")) return direction === "asc" ? aPrice - bPrice : bPrice - aPrice } ``` ```vue ``` ### Column Selection Use [SelectMenu](https://ui.nuxt.com/components/select-menu) to allow users to choose visible columns: ```vue ``` ### Column Styling Apply styles to table elements using `class` properties: ```vue ``` ## Sortable Enable column sorting with the `sortable` property: ```vue ``` ### Default Sorting Specify default sort settings with the `sort` prop: ```vue ``` ## Selectable Make rows selectable using `v-model`: ```vue ``` Use `by` prop for object comparison and `select` event for row click handling: ```vue ``` ### Sortable You can make the columns sortable by setting the `sortable` property to `true` in the column configuration. You may specify the default direction of each column through the `direction` property. It can be either `asc` or `desc`, but it will default to `asc`. ```vue ``` #### Default sorting You can specify a default sort for the table through the `sort` prop. It's an object with the following properties: - `column` - The column to sort by. - `direction` - The sort direction. Can be either `asc` or `desc` and defaults to `asc`. This will set the default sort and will work even if no column is set as `sortable`. ```vue ``` #### Reactive sorting You can use a `v-model:sort` to make the sorting reactive. You may also use `@update:sort` to call your own function with the sorting data. When fetching data from an API, we can take advantage of the `useFetch` or `useAsyncData` composables to fetch the data based on the sorting column and direction every time the `sort` reactive element changes. When doing so, you might want to set the `sort-mode` prop to `manual` to disable the automatic sorting and return the rows as is. ```vue ``` We pass a function to `useLazyFetch` here to make the url reactive but you can use the `query` / `params` options alongside `watch`. #### Custom sorting Use the `sort-button` prop to customize the sort button in the header. You can pass all the props of the [Button](https://ui.nuxt.com/components/button) component to customize it through this prop or globally through `ui.table.default.sortButton`. Its icon defaults to `i-heroicons-arrows-up-down-20-solid`. ```vue ``` Use the `sort-asc-icon` prop to set a different icon or change it globally in `ui.table.default.sortAscIcon`. Defaults to `i-heroicons-bars-arrow-up-20-solid`. Use the `sort-desc-icon` prop to set a different icon or change it globally in `ui.table.default.sortDescIcon`. Defaults to `i-heroicons-bars-arrow-down-20-solid`. You can also customize the entire header cell, read more in the [Slots](https://ui.nuxt.com/components/table#slots) section. ### Selectable Use a `v-model` to make the table selectable. The `v-model` will be an array of the selected rows. ```vue ``` You can use the `by` prop to compare objects by a field instead of comparing object instances. We've replicated the behavior of Headless UI [Combobox](https://headlessui.com/v1/vue/combobox#binding-objects-as-values). You can also add a `select` listener on your Table to make the rows clickable. The function will receive the row as the first argument. You can use this to navigate to a page, open a modal or even to select the row manually. ```vue ``` #### Event Selectable The `UTable` component provides two key events for handling row selection: ##### ***@select:all*** The `@select:all` event is emitted when the header checkbox in a selectable table is toggled. This event returns a boolean value indicating whether all rows are selected (true) or deselected (false). ##### ***@update:modelValue*** The `@update:modelValue` event is emitted whenever the selection state changes, including both individual row selection and bulk selection. This event returns an array containing the currently selected rows. Here's how to implement both events: ``` ``` #### Single Select Mode Control how the select function allows only one row to be selected at a time. ```vue ``` #### Checkbox Placement You can customize the checkbox column position by using the `select` key in the `columns` configuration. ```vue ``` ### Contextmenu #### Use the `contextmenu` listener on your Table to make the rows right-clickable. The function will receive the original event as the first argument and the row as the second argument.You can use this to open a [ContextMenu](https://ui.nuxt.com/components/context-menu) for that row. ```vue ``` ### Searchable You can easily use the [**Input**](https://ui.nuxt.com/components/input) component to filter the rows. ```vue ``` ### Paginable You can easily use the [Pagination](https://ui.nuxt.com/components/pagination) component to paginate the rows. ``` ``` ### Expandable You can use the `v-model:expand` to enables row expansion functionality in the table component. It maintains an object containing an `openedRows` an array and `row` an object, which tracks the indices of currently expanded rows. When using the expand slot, you have access to the `row` property in the slot scope, which contains the data of the row that triggered the expand/collapse action. This allows you to customize the expanded content based on the row's data. ```vue ``` #### Event expand The `@update:expand` event is emitted when a row is expanded. This event provides the current state of expanded rows and the data of the row that triggered the event. To use the `@update:expand` event, add it to your `UTable` component. The event handler will receive an object with the following properties: - `openedRows`: An array of indices of the currently expanded rows. - `row`: The row data that triggered the expand/collapse action. ```vue ``` #### Multiple expand Controls whether multiple rows can be expanded simultaneously in the table. ``` ``` #### Disable Row Expansion You can disable the expansion functionality for specific rows in the UTable component by adding the `disabledExpand` property to your row data. > *Important: When using* `disabledExpand`, you must define the `columns` prop for the UTable component. Otherwise, the table will render all properties as columns, including the `disabledExpand` property. ```vue ``` ### Loading Use the `loading` prop to indicate that data is currently loading with an indeterminate [Progress](https://ui.nuxt.com/components/progress#indeterminate) bar. You can use the `progress` prop to customize the `color` and `animation` of the progress bar or change them globally in `ui.table.default.progress` (you can set it to `null` to hide the progress bar). If there is no rows provided, a loading state will also be displayed. You can use the `loading-state` prop to customize the `icon` and `label` or change them globally in `ui.table.default.loadingState` (you can set it to `null` to hide the loading state). ```vue ``` This can be easily used with Nuxt `useAsyncData` composable. ```vue ``` ### Empty An empty state will be displayed when there are no results. Use the `empty-state` prop to customize the `icon` and `label` or change them globally in `ui.table.default.emptyState`. You can also set it to `null` to hide the empty state. ```vue ``` ## Slots You can use slots to customize the header and data cells of the table. ### `-header` Use the `#-header` slot to customize the header cell of a column. You will have access to the `column`, `sort` and `on-sort` properties in the slot scope. The `sort` property is an object with the following properties: - `field` - The field to sort by. - `direction` - The direction to sort by. Can be `asc` or `desc`. The `on-sort` property is a function that you can call to sort the table and accepts the column as parameter. > Even though you can customize the sort button as mentioned in the [Sortable](https://ui.nuxt.com/components/table#sortable) section, you can use this slot to completely override its behavior, with a custom dropdown for example. ### `-data` Use the `#-data` slot to customize the data cell of a column. You will have access to the��`row`, `column` and `getRowData` properties in the slot scope. You can for example create an extra column for actions with a [Dropdown](https://ui.nuxt.com/components/dropdown) component inside or change the color of the rows based on a selection. ```vue ``` ### `select-header` This slot allows you to customize the checkbox appearance in the table header for selecting all rows at once while using feature [Selectable](https://ui.nuxt.com/components/table#selectable). #### Usage ```vue ``` #### Props | **Prop** | **Type** | **Description** | | --- | --- | --- | | `checked` | `Boolean` | Indicates if all rows are selected | | `change` | `Function` | Function to handle selection state changes. Must receive a boolean value (true/false) | | `indeterminate` | `Boolean` | Indicates partial selection (when some rows are selected) | ```vue ``` ### `select-data` This slot allows you to customize the checkbox appearance for each row in the table while using feature [Selectable](https://ui.nuxt.com/components/table#selectable). #### Usage ```vue ``` #### Props | Prop | Type | Description | | --- | --- | --- | | `checked` | `Boolean` | Indicates if the current row is selected | | `change` | `Function` | Function to handle selection state changes. Must receive a boolean value (true/false) | #### Example ```vue ``` ### `expand-action` The `#expand-action` slot allows you to customize the expansion control interface for expandable table rows. This feature provides a flexible way to implement custom expand/collapse functionality while maintaining access to essential row data and state. #### Usage ```vue ``` #### Slot Props The slot provides three key props: | Prop | Type | Description | | --- | --- | --- | | `row` | `Object` | Contains the current row's data | | `toggle` | `Function` | Function to toggle the expanded state | | `isExpanded` | `Boolean` | Current expansion state of the row | ```vue ``` ### `loading-state` Use the `#loading-state` slot to customize the loading state. ```vue ``` ### `empty-state` Use the `#empty-state` slot to customize the empty state. ```vue ``` ### `caption` Use the `#caption` slot to customize the table's caption. ```vue ``` ## Props | Prop | Type | Default | | --- | --- | --- | | `sort` | \`{ column: string; direction: "asc" | "desc"; }\` | | `ui` | `object` | `{}` | | `caption` | `string` | `null` | | `progress` | \`{ color: string; animation: "carousel" | "carousel-inverse" | | `modelValue` | `unknown[]` | `null` | | `by` | \`string | Function\` | | `rows` | `TableRow[]` | `[]` | | `loadingState` | `{ icon: string; label: string; }` | `config.default.loadingState` | | `emptyState` | `{ icon: string; label: string; }` | `config.default.emptyState` | | `expand` | `Expanded` | `null` | | `columns` | `TableColumn[]` | `null` | | `columnAttribute` | `string` | `"label"` | | `sortMode` | \`"auto" | "manual"\` | | `sortButton` | `Button` | `config.default.sortButton` | | `sortAscIcon` | `string` | `config.default.sortAscIcon` | | `sortDescIcon` | `string` | `config.default.sortDescIcon` | | `expandButton` | `Button` | `config.default.expandButton` | | `loading` | `boolean` | `false` | | `multipleExpand` | `boolean` | `true` | | `singleSelect` | `boolean` | `false` | ## Config ```json { wrapper: 'relative overflow-x-auto', base: 'min-w-full table-fixed', divide: 'divide-y divide-gray-300 dark:divide-gray-700', thead: 'relative', tbody: 'divide-y divide-gray-200 dark:divide-gray-800', caption: 'sr-only', tr: { base: '', selected: 'bg-gray-50 dark:bg-gray-800/50', expanded: 'bg-gray-50 dark:bg-gray-800/50', active: 'hover:bg-gray-50 dark:hover:bg-gray-800/50 cursor-pointer' }, th: { base: 'text-left rtl:text-right', padding: 'px-4 py-3.5', color: 'text-gray-900 dark:text-white', font: 'font-semibold', size: 'text-sm' }, td: { base: 'whitespace-nowrap', padding: 'px-4 py-4', color: 'text-gray-500 dark:text-gray-400', font: '', size: 'text-sm' }, checkbox: { padding: 'ps-4' }, loadingState: { wrapper: 'flex flex-col items-center justify-center flex-1 px-6 py-14 sm:px-14', label: 'text-sm text-center text-gray-900 dark:text-white', icon: 'w-6 h-6 mx-auto text-gray-400 dark:text-gray-500 mb-4 animate-spin' }, emptyState: { wrapper: 'flex flex-col items-center justify-center flex-1 px-6 py-14 sm:px-14', label: 'text-sm text-center text-gray-900 dark:text-white', icon: 'w-6 h-6 mx-auto text-gray-400 dark:text-gray-500 mb-4' }, expand: { icon: 'transform transition-transform duration-200' }, progress: { wrapper: 'absolute inset-x-0 -bottom-[0.5px] p-0' }, default: { sortAscIcon: 'i-heroicons-bars-arrow-up-20-solid', sortDescIcon: 'i-heroicons-bars-arrow-down-20-solid', sortButton: { icon: 'i-heroicons-arrows-up-down-20-solid', trailing: true, square: true, color: 'gray', variant: 'ghost', class: '-m-1.5' }, expandButton: { icon: 'i-heroicons-chevron-down', color: 'gray', variant: 'ghost', size: 'xs', class: '-my-1.5 align-middle' }, checkbox: { color: 'primary' }, progress: { color: 'primary', animation: 'carousel' }, loadingState: { icon: 'i-heroicons-arrow-path-20-solid', label: 'Loading...' }, emptyState: { icon: 'i-heroicons-circle-stack-20-solid', label: 'No items.' } } } ```