Table Actions & Bulk Ops
Relevant source files
The following files were used as context for generating this wiki page:
Table Actions & Bulk Ops provide a specialized interface for performing operations on one or more selected rows within a data grid. This system decouples row selection logic from the execution of business logic, allowing developers to define custom actions that appear in a floating toolbar when rows are active. In the Better Tables architecture, this feature is implemented as an opt-in UI Module, ensuring the core table remains lightweight for consumers who do not require bulk processing capabilities.
The feature set includes row selection tracking, a dynamic ActionsToolbar for user interaction, and a configuration-driven action builder that integrates with the project's type-safe column and table definitions. By utilizing the TableAction type, developers can specify labels, icons, and asynchronous handlers that receive the currently selected row data, facilitating operations like bulk deletion, status updates, or data exports.
Sources: plans/059-ui-modules-and-actions-extraction.md:20-35, README.md:145-155, packages/ui/src/components/table/table.tsx:721
Architecture and UI Modules
The actions system is structured as a separate UI module rather than a hardcoded part of the core table. This allows for clean extraction and selective installation via the Better Tables CLI. The core table component provides a "slot" seam where the actions toolbar is injected if present.
Module Separation
As of the Wave D hygiene updates, the actions toolbar and its associated confirmation dialogs are moved out of the default init set of files. Consumers must explicitly add the module to their project.
| Element | Module Category | File Path |
|---|---|---|
| Core Table Logic | core | packages/ui/src/components/table/table.tsx |
| Actions Toolbar UI | actions | packages/ui/src/components/table/actions-toolbar.tsx |
| Confirmation Dialog | actions | packages/ui/src/components/table/action-confirmation-dialog.tsx |
Sources: plans/059-ui-modules-and-actions-extraction.md:65-80, plans/README.md:45-50
The Slot Seam
The BetterTable component uses a slots prop to render the actions interface. This prevents the core table from having direct imports of the actions module, maintaining the project's decoupled architecture. If actions are provided but the slot is not wired, the system issues a development-mode warning.
The diagram shows the logic flow for determining when and how the Actions Toolbar is rendered within the table component.
Sources: plans/059-ui-modules-and-actions-extraction.md:115-135, packages/ui/src/components/table/table.tsx:1292-1295
Defining Table Actions
Actions are defined as an array of TableAction objects passed to the BetterTable component. These definitions determine the behavior, appearance, and requirements of each bulk operation.
Action Configuration Structure
The TableAction type (defined in core types) allows for the following configuration:
- Label/Icon: The visual representation in the toolbar.
- Action Handler: An asynchronous function that receives the selected data.
- Selection Requirements: Logic to determine if the action is valid for the current selection.
Sources: packages/core/src/types/table.ts:74, plans/059-ui-modules-and-actions-extraction.md:70-75
Data Flow for Execution
When a user interacts with the toolbar, the system passes the internal selection state to the action handler.
This sequence diagram illustrates the flow from user selection to the execution of an asynchronous bulk action handler.
Sources: packages/ui/src/components/table/actions-toolbar.tsx:20-45, plans/059-ui-modules-and-actions-extraction.md:120-130
Row Selection & Integration
Row selection is the prerequisite for bulk operations. While the ActionsToolbar is a module, the logic for selection is handled by the core table features.
Selection Logic Features
- Automatic Activation: Row selection is automatically enabled if the
actionsarray is non-empty, even iffeatures.rowSelectionis explicitly set to false. - Checkbox Column: The table renders a selection checkbox column when actions are available to facilitate user input.
- Batch Selection: The toolbar typically includes a "Select All" toggle and a "Clear Selection" mechanism.
Sources: packages/ui/src/components/table/table.tsx:721, packages/ui/src/components/table/actions-toolbar.tsx:50-60, plans/059-ui-modules-and-actions-extraction.md:75-80
Selection State Management
The selection state is maintained within the table's internal store, providing reactive updates to the UI.
| Prop/Feature | Purpose | Source File |
|---|---|---|
rowSelection | Boolean flag in TableFeatures to enable checkboxes. | packages/core/src/types/table.ts |
onRowSelectionChange | Callback for external state synchronization. | packages/ui/src/components/table/table.tsx |
actions.length | Determines if the selection toolbar should be visible. | packages/ui/src/components/table/table.tsx |
Sources: packages/core/src/types/table.ts:139-168, packages/ui/src/components/table/table.tsx:698-725
Implementation as a Module
To use Table Actions in a project, developers follow a specific CLI-driven workflow to install and wire the module.
Installation via CLI
The @better-tables/cli provides an add command to inject the actions module files into a consumer's components directory.
bunx better-tables add actions
Sources: plans/059-ui-modules-and-actions-extraction.md:150-165, README.md:95-105
Manual Wiring
Once files are added, the module must be passed to the slots prop of the BetterTable component to be active.
import { ActionsToolbar } from '@/components/better-tables-ui/table/actions-toolbar';
<BetterTable
actions={myActions}
slots={{ actionsToolbar: ActionsToolbar }}
// ... other props
/>
Sources: plans/059-ui-modules-and-actions-extraction.md:180-195, packages/ui/src/components/table/table.tsx:49
Summary
Table Actions & Bulk Ops provide a robust mechanism for handling multi-row data processing. By leveraging a modular architecture, the system ensures that complex UI components like the ActionsToolbar remain optional and customizable, while row selection and action definition logic are maintained as type-safe primitives within the project core. This approach balances power for enterprise use cases with simplicity for basic data display needs.