URL state sync plugin for @bw-ui/datatable
npm install @bw-ui/datatable-url-stateURL state synchronization plugin for BWDataTable.
- 🔗 Shareable Links - Share table state via URL
- 🔄 State Persistence - Sort, filter survive page refresh
- ⬅️ Browser History - Back/forward navigation works
- ⚙️ Configurable - Choose what state to sync
- 🎯 Prefix Support - Multiple tables on same page
``bash`
npm install @bw-ui/datatable-url-state
`javascript
import { BWDataTable } from '@bw-ui/datatable';
import { UrlStatePlugin } from '@bw-ui/datatable-url-state';
const table = new BWDataTable('#table', { data }).use(UrlStatePlugin, {
persist: true, // Save state to URL (default: true)
restore: true, // Restore state from URL on load (default: true)
prefix: 'dt_', // URL param prefix (default: 'dt_')
useHash: false, // Use hash instead of query string (default: false)
debounce: 300, // Debounce URL updates (default: 300ms)
});
// URL automatically updates:
// - Sort: ?dt_sort=name&dt_dir=asc
// - Filter: ?dt_filter=john
// - Page: ?dt_page=2
`
| Option | Type | Default | Description |
| ----------- | ---------- | ---------------------------- | --------------------------------- |
| persist | boolean | true | Save state changes to URL |restore
| | boolean | true | Restore state from URL on init |prefix
| | string | 'dt_' | Prefix for URL parameters |useHash
| | boolean | false | Use hash (#) instead of query (?) |debounce
| | number | 300 | Debounce delay in milliseconds |syncState
| | string[] | ['sort', 'filter', 'page'] | Which state to sync |
With default prefix dt_:
| Parameter | Description | Example |
| ----------- | ------------------ | ---------------- |
| dt_sort | Sort column | dt_sort=name |dt_dir
| | Sort direction | dt_dir=asc |dt_filter
| | Search/filter term | dt_filter=john |dt_page
| | Page number | dt_page=2 |
`Sorted by name ascending
https://app.com/users?dt_sort=name&dt_dir=asc
API
$3
`javascript
// Get shareable URL
const url = table.getShareableUrl?.();
// Returns: "https://app.com/users?dt_sort=name&dt_dir=asc"// Get URL state plugin instance
const urlState = table.plugins?.find((p) => p.name === 'url-state');
// Get current state from URL
const state = urlState?.getState();
// Returns: { sortColumn: 'name', sortDirection: 'asc', filter: '' }
// Set state programmatically
urlState?.setState({ sortColumn: 'email', sortDirection: 'desc' });
// Clear all URL state
urlState?.clearState();
`Events
`javascript
// State changed and URL updated
table.on('urlstate:change', ({ previous, current, url }) => {
console.log('URL state changed:', current);
console.log('New URL:', url);
});// State restored from URL on init
table.on('urlstate:restore', (state) => {
console.log('Restored from URL:', state);
});
`Example: Share Button
`html
``javascript
const table = new BWDataTable('#table', { data }).use(UrlStatePlugin);document.getElementById('share').addEventListener('click', async () => {
const url = window.location.href;
try {
await navigator.clipboard.writeText(url);
alert('Link copied to clipboard!');
} catch {
prompt('Copy this link:', url);
}
});
`Example: Multiple Tables
`javascript
// Table 1
const table1 = new BWDataTable('#users', { data: users }).use(UrlStatePlugin, {
prefix: 'users_',
});// Table 2
const table2 = new BWDataTable('#orders', { data: orders }).use(
UrlStatePlugin,
{ prefix: 'orders_' }
);
// URL: ?users_sort=name&orders_sort=date
`Example: Hash-based State
Useful for single-page apps where you can't change query string:
`javascript
const table = new BWDataTable('#table', { data }).use(UrlStatePlugin, {
useHash: true,
});// URL: https://app.com/users#dt_sort=name&dt_dir=asc
`Browser History
The plugin integrates with browser history:
- Back button - Reverts to previous state
- Forward button - Re-applies state
- Page refresh - Restores state from URL
`javascript
// Listen for browser navigation
window.addEventListener('popstate', () => {
// Plugin automatically handles this
});
`TypeScript
`typescript
import { BWDataTable } from '@bw-ui/datatable';
import {
UrlStatePlugin,
UrlStatePluginOptions,
UrlState,
} from '@bw-ui/datatable-url-state';const options: UrlStatePluginOptions = {
persist: true,
restore: true,
prefix: 'tbl_',
syncState: ['sort', 'filter'],
};
const table = new BWDataTable('#table', { data }).use(UrlStatePlugin, options);
table.on('urlstate:change', ({ current }: { current: UrlState }) => {
console.log('Sort:', current.sortColumn, current.sortDirection);
});
``- URL updates are debounced to prevent excessive history entries
- State is restored after table initialization
- Works with both hash and query string modes
- Handles URL encoding/decoding automatically
MIT © BW UI