Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
6 changes: 3 additions & 3 deletions docs/framework/alpine/guide/column-ordering.md
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@ By default, columns are ordered in the order they are defined in the `columns` a

There are 3 table features that can reorder columns, which happen in the following order:

1. [Column Pinning](./column-pinning) - If pinning, columns are split into left, center (unpinned), and right pinned columns.
1. [Column Pinning](./column-pinning) - If pinning, columns are split into start, center (unpinned), and end pinned columns.
2. Manual **Column Ordering** - A manually specified column order is applied.
3. [Grouping](./grouping) - If grouping is enabled, a grouping state is active, and `tableOptions.groupedColumnMode` is set to `'reorder' | 'remove'`, then the grouped columns are reordered to the start of the column flow.

Expand Down Expand Up @@ -173,9 +173,9 @@ Columns expose helpers for reading their current position after column pinning,

```ts
column.getIndex()
column.getIndex('left')
column.getIndex('start')
column.getIndex('center')
column.getIndex('right')
column.getIndex('end')

column.getIsFirstColumn()
column.getIsLastColumn()
Expand Down
72 changes: 37 additions & 35 deletions docs/framework/alpine/guide/column-pinning.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,17 +36,19 @@ const table = createTable({

## Column Pinning (Alpine) Guide

TanStack Table offers state and APIs helpful for implementing column pinning features in your table UI. You can implement column pinning in multiple ways. You can either split pinned columns into their own separate tables, or you can keep all columns in the same table, but use the pinning state to order the columns correctly and use sticky CSS to pin the columns to the left or right.
TanStack Table offers state and APIs helpful for implementing column pinning features in your table UI. You can implement column pinning in multiple ways. You can either split pinned columns into their own separate tables, or you can keep all columns in the same table, but use the pinning state to order the columns correctly and use sticky CSS to pin the columns to the start or end.

`start` and `end` are logical pinning regions. In LTR languages/layouts, `start` usually corresponds to left and `end` to right. In RTL languages/layouts, `start` usually corresponds to right and `end` to left.

### How Column Pinning Affects Column Order

There are 3 table features that can reorder columns, which happen in the following order:

1. **Column Pinning** - If pinning, columns are split into left, center (unpinned), and right pinned columns.
1. **Column Pinning** - If pinning, columns are split into start, center (unpinned), and end pinned columns.
2. Manual [Column Ordering](./column-ordering) - A manually specified column order is applied.
3. [Grouping](./grouping) - If grouping is enabled, a grouping state is active, and `tableOptions.groupedColumnMode` is set to `'reorder' | 'remove'`, then the grouped columns are reordered to the start of the column flow.

The only way to change the order of the pinned columns is in the `columnPinning.left` and `columnPinning.right` state itself. `columnOrder` state will only affect the order of the unpinned ("center") columns.
The only way to change the order of the pinned columns is in the `columnPinning.start` and `columnPinning.end` state itself. `columnOrder` state will only affect the order of the unpinned ("center") columns.

### Column Pinning State

Expand All @@ -66,8 +68,8 @@ import type { ColumnPinningState } from '@tanstack/alpine-table'
const features = tableFeatures({ columnPinningFeature })

const columnPinningAtom = createAtom<ColumnPinningState>({
left: [],
right: [],
start: [],
end: [],
})

// subscribe wherever it is needed
Expand All @@ -89,7 +91,7 @@ Alternatively, the v8-style `state.columnPinning` plus `onColumnPinningChange` p

```ts
const local = Alpine.reactive({
columnPinning: { left: [], right: [] } as ColumnPinningState,
columnPinning: { start: [], end: [] } as ColumnPinningState,
})

const table = createTable({
Expand Down Expand Up @@ -119,8 +121,8 @@ const table = createTable({
//...
initialState: {
columnPinning: {
left: ['expand-column'],
right: ['actions-column'],
start: ['expand-column'],
end: ['actions-column'],
},
//...
},
Expand All @@ -135,20 +137,20 @@ const table = createTable({
There are a handful of useful Column API methods to help you implement column pinning features:

- `column.getCanPin`: Use to determine if a column can be pinned.
- `column.pin`: Use to pin a column to the left or right. Or use to unpin a column.
- `column.pin`: Use to pin a column to the start or end. Or use to unpin a column.
- `column.getIsPinned`: Use to determine where a column is pinned.
- `column.getPinnedIndex`: Use to read the column's index within its pinned column group.
- `column.getStart`: Use to provide the correct `left` CSS value for a pinned column.
- `column.getAfter`: Use to provide the correct `right` CSS value for a pinned column.
- `column.getStart`: Use to provide the correct `start` CSS value for a pinned column.
- `column.getAfter`: Use to provide the correct `end` CSS value for a pinned column.
- `column.getIsLastColumn`: Use to determine if a column is the last column in its pinned group. Useful for adding a box-shadow.
- `column.getIsFirstColumn`: Use to determine if a column is the first column in its pinned group. Useful for adding a box-shadow.

Use `table.setColumnPinning` to update the pinning state directly. Use `table.resetColumnPinning` to reset to `initialState.columnPinning`, or pass `true` to clear both pinned column arrays.

```ts
table.setColumnPinning({
left: ['firstName'],
right: ['actions'],
start: ['firstName'],
end: ['actions'],
})

table.resetColumnPinning()
Expand All @@ -158,44 +160,44 @@ table.resetColumnPinning(true)
The table instance exposes pinned column and header helpers for each region:

```ts
table.getLeftLeafColumns()
table.getStartLeafColumns()
table.getCenterLeafColumns()
table.getRightLeafColumns()
table.getEndLeafColumns()

table.getLeftVisibleLeafColumns()
table.getStartVisibleLeafColumns()
table.getCenterVisibleLeafColumns()
table.getRightVisibleLeafColumns()
table.getEndVisibleLeafColumns()

table.getLeftHeaderGroups()
table.getStartHeaderGroups()
table.getCenterHeaderGroups()
table.getRightHeaderGroups()
table.getEndHeaderGroups()

table.getLeftFooterGroups()
table.getStartFooterGroups()
table.getCenterFooterGroups()
table.getRightFooterGroups()
table.getEndFooterGroups()

table.getLeftFlatHeaders()
table.getStartFlatHeaders()
table.getCenterFlatHeaders()
table.getRightFlatHeaders()
table.getEndFlatHeaders()

table.getLeftLeafHeaders()
table.getStartLeafHeaders()
table.getCenterLeafHeaders()
table.getRightLeafHeaders()
table.getEndLeafHeaders()
```

You can also request pinned leaf columns by region with `table.getPinnedLeafColumns(position)` and visible pinned leaf columns with `table.getPinnedVisibleLeafColumns(position)`.

```ts
table.getPinnedLeafColumns('left')
table.getPinnedLeafColumns('start')
table.getPinnedLeafColumns('center')
table.getPinnedLeafColumns('right')
table.getPinnedLeafColumns('end')

table.getPinnedVisibleLeafColumns('left')
table.getPinnedVisibleLeafColumns('start')
table.getPinnedVisibleLeafColumns('center')
table.getPinnedVisibleLeafColumns('right')
table.getPinnedVisibleLeafColumns('end')
```

Use `table.getIsSomeColumnsPinned()` to check if any columns are pinned, or pass `'left'` or `'right'` to check one pinned side.
Use `table.getIsSomeColumnsPinned()` to check if any columns are pinned, or pass `'start'` or `'end'` to check one pinned side.

### Wiring up the pinning UI

Expand All @@ -211,8 +213,8 @@ Because Alpine does not initialize directives inside content set with `x-html`,
<template x-if="!header.isPlaceholder && header.column.getCanPin()">
<div class="pin-actions">
<button
x-show="header.column.getIsPinned() !== 'left'"
@click="header.column.pin('left')"
x-show="header.column.getIsPinned() !== 'start'"
@click="header.column.pin('start')"
>
&lt;=
</button>
Expand All @@ -223,8 +225,8 @@ Because Alpine does not initialize directives inside content set with `x-html`,
X
</button>
<button
x-show="header.column.getIsPinned() !== 'right'"
@click="header.column.pin('right')"
x-show="header.column.getIsPinned() !== 'end'"
@click="header.column.pin('end')"
>
=&gt;
</button>
Expand All @@ -237,4 +239,4 @@ Because Alpine does not initialize directives inside content set with `x-html`,

If you are just using sticky CSS to pin columns, you can for the most part, just render the table as you normally would with the `table.getHeaderGroups` and `row.getVisibleCells` methods.

However, if you are splitting up pinned columns into their own separate tables, you can make use of the `table.getLeftHeaderGroups`, `table.getCenterHeaderGroups`, `table.getRightHeaderGroups`, `row.getLeftVisibleCells`, `row.getCenterVisibleCells`, and `row.getRightVisibleCells` methods to only render the columns that are relevant to the current table.
However, if you are splitting up pinned columns into their own separate tables, you can make use of the `table.getStartHeaderGroups`, `table.getCenterHeaderGroups`, `table.getEndHeaderGroups`, `row.getStartVisibleCells`, `row.getCenterVisibleCells`, and `row.getEndVisibleCells` methods to only render the columns that are relevant to the current table.
16 changes: 8 additions & 8 deletions docs/framework/alpine/guide/column-sizing.md
Original file line number Diff line number Diff line change
Expand Up @@ -135,15 +135,15 @@ Use the column and header APIs to read the calculated size and offsets for rende
column.getSize()
header.getSize()

column.getStart() // left offset in the current column flow
column.getStart('left')
column.getStart() // start offset in the current column flow
column.getStart('start')
column.getStart('center')
column.getStart('right')
column.getStart('end')

column.getAfter() // right offset in the current column flow
column.getAfter('left')
column.getAfter() // end offset in the current column flow
column.getAfter('start')
column.getAfter('center')
column.getAfter('right')
column.getAfter('end')

column.resetSize()
```
Expand All @@ -152,9 +152,9 @@ The table instance also exposes total size helpers. These are useful when buildi

```ts
table.getTotalSize()
table.getLeftTotalSize()
table.getStartTotalSize()
table.getCenterTotalSize()
table.getRightTotalSize()
table.getEndTotalSize()
```

If you need to update sizing state directly, use `table.setColumnSizing`. Use `table.resetColumnSizing` to reset to `initialState.columnSizing`, or pass `true` to reset to the feature default.
Expand Down
2 changes: 1 addition & 1 deletion docs/framework/alpine/guide/grouping.md
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,7 @@ Grouping in TanStack table is a feature that applies to columns and allows you t

Grouping can also affect column order. There are 3 table features that can reorder columns, which happen in the following order:

1. [Column Pinning](./column-pinning) - If pinning, columns are split into left, center (unpinned), and right pinned columns.
1. [Column Pinning](./column-pinning) - If pinning, columns are split into start, center (unpinned), and end pinned columns.
2. Manual [Column Ordering](./column-ordering) - A manually specified column order is applied.
3. **Grouping** - If grouping is enabled, a grouping state is active, and `tableOptions.groupedColumnMode` is set to `'reorder' | 'remove'`, then the grouped columns are reordered to the start of the column flow.

Expand Down
25 changes: 23 additions & 2 deletions docs/framework/alpine/reference/functions/createTable.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,10 +6,21 @@ title: createTable
# Function: createTable()

```ts
function createTable<TFeatures, TData>(tableOptions): AlpineTable<TFeatures, TData>;
function createTable<TFeatures, TData>(tableOptions, selector?): AlpineTable<TFeatures, TData>;
```

Defined in: [createTable.ts:27](https://github.com/TanStack/table/blob/main/packages/alpine-table/src/createTable.ts#L27)
Defined in: [createTable.ts:46](https://github.com/TanStack/table/blob/main/packages/alpine-table/src/createTable.ts#L46)

Creates an Alpine-reactive table instance.

Reactivity is bridged through a single version counter that every proxied
table read registers as a dependency, so by default ANY state change
re-evaluates every Alpine binding that touches the table. Pass a `selector`
to gate that: the counter then only bumps when the selected slice of state
changes (shallow compare). Use `() => ({})` to opt out of state-driven
re-evaluation entirely and handle high-frequency state (e.g. column
resizing) with explicit `table.atoms.<slice>.subscribe()` side effects.
Options changes (e.g. new `data`) always re-evaluate.

## Type Parameters

Expand All @@ -27,6 +38,16 @@ Defined in: [createTable.ts:27](https://github.com/TanStack/table/blob/main/pack

`TableOptions`\<`TFeatures`, `TData`\>

### selector?

(`state`) => `unknown`

## Returns

[`AlpineTable`](../type-aliases/AlpineTable.md)\<`TFeatures`, `TData`\>

## Example

```ts
const table = createTable(options, (state) => ({ sorting: state.sorting }))
```
8 changes: 6 additions & 2 deletions docs/framework/alpine/reference/functions/createTableHook.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ title: createTableHook
function createTableHook<TFeatures>(__namedParameters): object;
```

Defined in: [createTableHook.ts:21](https://github.com/TanStack/table/blob/main/packages/alpine-table/src/createTableHook.ts#L21)
Defined in: [createTableHook.ts:26](https://github.com/TanStack/table/blob/main/packages/alpine-table/src/createTableHook.ts#L26)

## Type Parameters

Expand Down Expand Up @@ -52,7 +52,7 @@ createAppColumnHelper: <TData>() => ColumnHelper<TFeatures, TData>;
### createAppTable()

```ts
createAppTable: <TData>(tableOptions) => AppAlpineTable<TFeatures, TData>;
createAppTable: <TData>(tableOptions, selector?) => AppAlpineTable<TFeatures, TData>;
```

#### Type Parameters
Expand All @@ -67,6 +67,10 @@ createAppTable: <TData>(tableOptions) => AppAlpineTable<TFeatures, TData>;

`Omit`\<`TableOptions`\<`TFeatures`, `TData`\>, `"features"`\>

##### selector?

(`state`) => `unknown`

#### Returns

[`AppAlpineTable`](../type-aliases/AppAlpineTable.md)\<`TFeatures`, `TData`\>
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ title: AlpineTable
type AlpineTable<TFeatures, TData> = Table<TFeatures, TData> & object;
```

Defined in: [createTable.ts:12](https://github.com/TanStack/table/blob/main/packages/alpine-table/src/createTable.ts#L12)
Defined in: [createTable.ts:14](https://github.com/TanStack/table/blob/main/packages/alpine-table/src/createTable.ts#L14)

## Type Declaration

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ title: AppAlpineTable
type AppAlpineTable<TFeatures, TData> = AlpineTable<TFeatures, TData>;
```

Defined in: [createTableHook.ts:11](https://github.com/TanStack/table/blob/main/packages/alpine-table/src/createTableHook.ts#L11)
Defined in: [createTableHook.ts:16](https://github.com/TanStack/table/blob/main/packages/alpine-table/src/createTableHook.ts#L16)

## Type Parameters

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ title: AppColumnHelper
type AppColumnHelper<TFeatures, TData> = ReturnType<typeof coreCreateColumnHelper>;
```

Defined in: [createTableHook.ts:16](https://github.com/TanStack/table/blob/main/packages/alpine-table/src/createTableHook.ts#L16)
Defined in: [createTableHook.ts:21](https://github.com/TanStack/table/blob/main/packages/alpine-table/src/createTableHook.ts#L21)

## Type Parameters

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ title: CreateTableHookOptions
type CreateTableHookOptions<TFeatures> = Omit<TableOptions<TFeatures, any>, "columns" | "data" | "state">;
```

Defined in: [createTableHook.ts:6](https://github.com/TanStack/table/blob/main/packages/alpine-table/src/createTableHook.ts#L6)
Defined in: [createTableHook.ts:11](https://github.com/TanStack/table/blob/main/packages/alpine-table/src/createTableHook.ts#L11)

## Type Parameters

Expand Down
6 changes: 3 additions & 3 deletions docs/framework/angular/guide/column-ordering.md
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,7 @@ By default, columns are ordered in the order they are defined in the `columns` a

There are 3 table features that can reorder columns, which happen in the following order:

1. [Column Pinning](./column-pinning) - If pinning, columns are split into left, center (unpinned), and right pinned columns.
1. [Column Pinning](./column-pinning) - If pinning, columns are split into start, center (unpinned), and end pinned columns.
2. Manual **Column Ordering** - A manually specified column order is applied.
3. [Grouping](./grouping) - If grouping is enabled, a grouping state is active, and `tableOptions.groupedColumnMode` is set to `'reorder' | 'remove'`, then the grouped columns are reordered to the start of the column flow.

Expand Down Expand Up @@ -179,9 +179,9 @@ Columns expose helpers for reading their current position after column pinning,

```ts
column.getIndex()
column.getIndex('left')
column.getIndex('start')
column.getIndex('center')
column.getIndex('right')
column.getIndex('end')

column.getIsFirstColumn()
column.getIsLastColumn()
Expand Down
Loading
Loading