Template Refs

Introduction

Template refs allow you to access the table's internal methods and state programmatically while still using the default Table component. This gives you access to all the functionality from the useTable and useActions composables without having to create a custom table.

This is useful when you need to programmatically trigger table actions, integrate with other components, or build custom controls that interact with the table state.

Basic Usage

To access the table's methods, create a template ref and call the exposed methods:

Vue

<script setup>
import { ref } from 'vue'
import { Table } from '@inertiaui/table-vue'

const props = defineProps({
    users: Object,
})

const tableRef = ref()

function addFilter() {
    const filter = props.users.filters.find(f => f.attribute === 'status')
    tableRef.value.addFilter(filter)
}

function selectAll() {
    tableRef.value.toggleItem('*')
}
</script>

<template>
    <Table ref="tableRef" :resource="users" />
</template>

React

import { useRef } from 'react'
import { Table } from '@inertiaui/table-react'

export default function Users({ users }) {
    const tableRef = useRef()

    function addFilter() {
        const filter = users.filters.find(f => f.attribute === 'status')
        tableRef.current.addFilter(filter)
    }

    function selectAll() {
        tableRef.current.toggleItem('*')
    }

    return <Table ref={tableRef} resource={users} />
}

Table Methods

Method	Description
addFilter(filter)	Add a filter
removeFilter(filter)	Remove a filter
toggleColumn(column)	Show/hide a column
setSort(sort)	Set the table sort
setPerPage(perPage)	Change items per page
makeSticky(column)	Make columns sticky
undoSticky(column)	Remove sticky positioning
putState(newState)	Replace the table state
toggleItem(key)	Toggle item selection (use '*' for all)
performAction(action, keys)	Execute an action

Table State

Property	Type	Description
state	Object	Reactive table state
hasFilters	Boolean	Whether filters are active
hasSelectableRows	Boolean	Whether rows are selectable
selectedItems	Array	Selected item keys
allItemsAreSelected	Boolean	Whether all items are selected
isNavigating	Boolean	Whether navigating

Accessing State

You can access the table's reactive state. In Vue, the state is automatically reactive. In React, you'll typically access the state in response to user interactions or component lifecycle events:

Vue

<script setup>
import { ref } from 'vue'
import { Table } from '@inertiaui/table-vue'

const props = defineProps({
    users: Object,
})

const tableRef = ref()

function checkState() {
    // Access state when needed
    const selectedItems = tableRef.value.selectedItems
    const currentSearch = tableRef.value.state.search

    console.log(`Selected ${selectedItems.length} items`)
    console.log(`Current search: ${currentSearch}`)
}
</script>

<template>
    <div>
        <button @click="checkState">
            Check State
        </button>
        <Table ref="tableRef" :resource="users" />
    </div>
</template>

React

function MyComponent({ users }) {
    const tableRef = useRef()

    function checkState() {
        // Access state when needed
        const selectedItems = tableRef.current.selectedItems
        const currentSearch = tableRef.current.state.search

        console.log(`Selected ${selectedItems.length} items`)
        console.log(`Current search: ${currentSearch}`)
    }

    return (
        <div>
            <button onClick={checkState}>
                Check State
            </button>
            <Table ref={tableRef} resource={users} />
        </div>
    )
}

Custom Filter Controls

You can create custom filter interfaces that integrate with the table's filtering system:

Vue

<script setup>
import { ref } from 'vue'
import { Table } from '@inertiaui/table-vue'

const props = defineProps({
    users: Object,
})

const tableRef = ref()

function applyStatusFilter(status) {
    const filter = props.users.filters.find(f => f.attribute === 'status')
    tableRef.value.addFilter(filter)
    tableRef.value.state.filters.status.value = status
    tableRef.value.state.filters.status.clause = 'equals'
}
</script>

<template>
    <div class="mb-4 space-x-2">
        <button @click="applyStatusFilter('active')">Show Active</button>
        <button @click="applyStatusFilter('inactive')">Show Inactive</button>
    </div>

    <Table ref="tableRef" :resource="users" />
</template>

React

function MyComponent({ users }) {
    const tableRef = useRef()

    function applyStatusFilter(status) {
        const filter = users.filters.find(f => f.attribute === 'status')
        tableRef.current.addFilter(filter)
        tableRef.current.setFilter(filter, 'equals', status)
    }

    return (
        <div>
            <div className="mb-4 space-x-2">
                <button onClick={() => applyStatusFilter('active')}>
                    Show Active
                </button>
                <button onClick={() => applyStatusFilter('inactive')}>
                    Show Inactive
                </button>
            </div>

            <Table ref={tableRef} resource={users} />
        </div>
    )
}

Custom Bulk Actions

You can trigger bulk actions programmatically and control row selection:

Vue

<script setup>
import { ref } from 'vue'
import { Table } from '@inertiaui/table-vue'

const props = defineProps({
    users: Object,
})

const tableRef = ref()

function selectAll() {
    tableRef.value.toggleItem('*')
}

function bulkDelete() {
    const deleteAction = props.users.actions.find(a => a.id === 'delete')

    if (deleteAction && tableRef.value.selectedItems.length > 0) {
        tableRef.value.performAction(deleteAction, tableRef.value.selectedItems)
    }
}
</script>

<template>
    <div class="mb-4 space-x-2">
        <button @click="selectAll">Toggle All</button>
        <button @click="bulkDelete" :disabled="!tableRef?.selectedItems?.length">
            Delete Selected ({{ tableRef?.selectedItems?.length || 0 }})
        </button>
    </div>

    <Table ref="tableRef" :resource="users" />
</template>

React

function MyComponent({ users }) {
    const tableRef = useRef()

    function selectAll() {
        tableRef.current.toggleItem('*')
    }

    function bulkDelete() {
        const deleteAction = users.actions.find(a => a.id === 'delete')

        if (deleteAction && tableRef.current.selectedItems.length > 0) {
            tableRef.current.performAction(deleteAction, tableRef.current.selectedItems)
        }
    }

    return (
        <div>
            <div className="mb-4 space-x-2">
                <button onClick={selectAll}>Toggle All</button>
                <button onClick={bulkDelete}>
                    Delete Selected
                </button>
            </div>

            <Table ref={tableRef} resource={users} />
        </div>
    )
}