@vincjo/datatables

The table state is a structured object used to track the current configuration of the data table, including pagination, searching, sorting, and filtering. This state can be used to synchronize the UI with backend API requests.

Key properties include:

• currentPage: The current active page number.
• rowsPerPage: The number of rows to display per page.
• offset: The starting index for the current view (calculated as (currentPage - 1) * rowsPerPage).
• search: The full-text search string.
• sort: An object containing the field being sorted and the direction (asc or desc).
• filters: An array of objects, where each object contains a field and a value to filter by.

state = {
    currentPage: 3,
    rowsPerPage: 10,
    offset: 20,
    search: 'michel',
    sort: { field: 'age', direction: 'desc' },
    filters: [ { field: 'city', value: 'limoge' } ]
}

To enable row selection in a TableHandler instance, you must specify which property in your data objects serves as the unique identifier by providing the selectBy parameter in the configuration object. This allows the handler to track which rows are selected based on their unique keys.

const table = new TableHandler(data, { selectBy: 'id' })

Install the datatables toolkit as a development dependency using npm.

npm i -D @vincjo/datatables

The isLoading property on the table object is a boolean that becomes true whenever the invalidate() method is running (e.g., during data fetching or refreshing). You can use this property to conditionally render loading spinners or progress indicators in your Svelte components.

<Datatable {table}>
    <div class="spinner" class={{ active: table.isLoading }}></div
    <table>
        [...]
    </table>
</Datatable>

To facilitate a progressive upgrade, version 1 functionality is available under the legacy namespace. You can migrate your existing components by updating your import paths from the main package to the legacy subpaths.

- @vincjo/datatables
+ @vincjo/datatables/legacy

- @vincjo/datatables/remote
+ @vincjo/datatables/legacy/remote

You can customize the text used in various datatable components using the Internationalization type. The available keys are:

• search: Label for the search input.
• show: Label for showing entries.
• entries: Label for entries.
• filter: Label for filtering.
• rowCount: Label for the row count display.
• noRows: Label for when no results are found.
• previous: Label for the previous page button.
• next: Label for the next page button.

When using Svelte's $effect to react to data changes, you can prevent the table from automatically restoring previous sorts by clearing them before the update. Use the following pattern:

<script lang="ts">
    $effect(() => { 
        data
        table.clearSort()
        table.setRows(data) 
    })
</script>

If you are not using the built-in <Datatable/> component, you must manually bind the clientWidth property to a container element using Svelte's bind:clientWidth directive to ensure the value stays updated.

<article bind:clientWidth={table.clientWidth}>
    <table>
        <thead>[...]</thead>
        <tbody></tbody>
    </table>
</article>

To manage row selection in a Svelte component, use the table.selected array to track which row identifiers are currently active and the table.select(id) method to toggle or set selection.

When rendering rows, you can check if a row is selected by verifying if its identifier exists within table.selected using .includes(row.id). This allows you to apply conditional CSS classes (like active) and manage the state of checkbox inputs.

<tr class={{ active: table.selected.includes(row.id) }}>
    <td>
        <input type="checkbox" 
            checked={table.selected.includes(row.id)}
            onclick={() => table.select(row.id)}
        >
    </td>
    <td>{row.first_name}</td>
    <td>{row.last_name}</td>
</tr>

To render the data in a Svelte component, iterate over the table.rows array using an {#each} block. Each row object in the array contains the data for a single record. You can access individual fields (e.g., row.first_name, row.last_name) to populate your table cells (<td>).

<tbody
>
    {#each table.rows as row}
        <tr>
            <td>{row.first_name}</td> 
            <td>{row.last_name}</td>
            <td>{row.address}</td>
        </tr>
    {/each}
</tbody
>