Table Preferences

User-customizable column visibility, column ordering, and filter visibility for DataTable instances.

Overview

The Table Preferences system allows end users to personalize their table experience by:

Toggling column visibility (show/hide columns)
Reordering columns via drag-and-drop
Toggling filter visibility (show/hide filters)
Persisting preferences across sessions (localStorage + API backup)
Resetting to defaults when needed

The system consists of two parts:

Component	Location	Purpose
`useTablePreferences` composable	`@/composables/useTablePreferences.js`	State management, persistence, merge logic
`TablePreferences` component	`@/components/interface/Table/Preferences/TablePreferences.offcanvas.vue`	UI panel for configuring preferences

Architecture

Persistence Flow

useTablePreferences Composable

Import and Usage

javascript

import { useTablePreferences } from '@/composables/useTablePreferences';

const {
    visibleColumns,
    visibleFilters,
    draftColumns,
    draftFilters,
    toggleColumn,
    reorderColumns,
    toggleFilter,
    resetDefaults,
    initDraft,
    save,
    saving,
} = useTablePreferences('my-table-id', {
    allColumns,
    allFilters,
    defaults: MY_TABLE_DEFAULTS,
});

Parameters

Parameter	Type	Required	Description
`tableId`	`string`	Yes	Unique identifier for the table (e.g. `'crm-prospects'`). Used as localStorage key and API identifier.
`options.allColumns`	`Ref<Array> \| Array`	Yes	All available column definitions. Each column must have at least `text` and `value`.
`options.allFilters`	`Ref<Object> \| Object`	No	All available filter definitions, keyed by filter name.
`options.defaults`	`Object`	No	Default preferences `{ columns: [...], filters: [...] }`. If not provided, all columns/filters are visible by default.

Returned Values

Return	Type	Description
`mergedColumns`	`ComputedRef<Array>`	All columns merged with saved preferences (includes hidden ones)
`visibleColumns`	`ComputedRef<Array>`	Only visible columns, sorted by order. Pass this to DataTable's `:columns` prop.
`mergedFilters`	`ComputedRef<Object>`	All filters merged with saved preferences
`visibleFilters`	`ComputedRef<Object>`	Only visible filters. Pass this to DataTable's `:filters` prop.
`draftColumns`	`ComputedRef<Array>`	Draft columns for the preferences UI
`draftFilters`	`ComputedRef<Object>`	Draft filters for the preferences UI
`toggleColumn`	`Function(value)`	Toggle a column's visibility in draft state
`reorderColumns`	`Function(string[])`	Set new column order in draft state
`toggleFilter`	`Function(key)`	Toggle a filter's visibility in draft state
`resetDefaults`	`Function`	Reset draft state to defaults
`initDraft`	`Function`	Sync draft state from saved state (call before opening the preferences panel)
`save`	`Function`	Persist draft to localStorage and API
`saving`	`Ref<boolean>`	Loading flag during save

Draft vs Saved State

The composable uses a two-phase commit pattern:

Draft state (draftColumns, draftFilters): In-memory working copy. Modified by toggleColumn, reorderColumns, toggleFilter.
Saved state (mergedColumns, visibleColumns, etc.): Persisted state. Only updated when save() is called.

This means users can toggle columns/filters in the preferences panel without affecting the table until they explicitly save.

Defaults File

Define a defaults file to control the initial column visibility/order and filter visibility for new users.

Structure

javascript

export const MY_TABLE_DEFAULTS = {
    columns: [
        { value: 'name', visible: true, order: 0 },
        { value: 'email', visible: true, order: 1 },
        { value: 'status', visible: true, order: 2 },
        { value: 'created_at', visible: false, order: 3 },
        { value: 'notes', visible: false, order: 4 },
    ],
    filters: [
        { key: 'search', visible: true },
        { key: 'status', visible: true },
        { key: 'dateRange', visible: false },
    ],
};

Column Defaults

Property	Type	Description
`value`	`string`	Must match the `value` property in `allColumns`
`visible`	`boolean`	Whether the column is visible by default
`order`	`number`	Display order (0-based)

Filter Defaults

Property	Type	Description
`key`	`string`	Must match the key in the `allFilters` object
`visible`	`boolean`	Whether the filter is visible by default

Real Example: CRM Table

javascript

// frontend/client/src/views/crm/constants/table.defaults.js
export const CRM_TABLE_DEFAULTS = {
    columns: [
        { value: 'company_name', visible: true, order: 0 },
        { value: 'follow_name', visible: true, order: 1 },
        { value: 'lead_status', visible: true, order: 2 },
        { value: 'salesman_name', visible: false, order: 3 },
        { value: 'balance', visible: true, order: 4 },
        { value: 'account_value', visible: true, order: 5 },
        // ... more columns
    ],
    filters: [
        { key: 'search', visible: true },
        { key: 'follow', visible: true },
        { key: 'onboarding', visible: true },
        { key: 'ecommerce', visible: true },
        { key: 'type', visible: true },
        { key: 'createdAt', visible: true },
        { key: 'campaing', visible: false },
        // ... more filters
    ],
};

Locked Columns and Filters

Columns and filters can be marked as locked to prevent users from hiding them.

Locked Column

javascript

const allColumns = computed(() => [
    {
        text: t('datatable.column.company'),
        value: 'company_name',
        sortable: true,
        locked: true, // Cannot be hidden or reordered
    },
    // ...
    {
        text: t('datatable.column.actions'),
        value: 'actions',
        sortable: false,
        locked: true,    // Cannot be hidden
        exportable: false,
        width: 100,
    },
]);

Locked Filter

javascript

const allFilters = computed(() => ({
    search: {
        className: 'col-12 col-lg-2 mb-2',
        label: t('filters.search'),
        el: 'input',
        locked: true, // Cannot be hidden
    },
    // ...
}));