(v9) API proposal: Use logical start/end instead of physical left/right for Column Pinning

[na-pel]

First of all, thank you for the amazing work on TanStack Table. This is one of the most thoughtfully designed headless table libraries I've used.

I'd like to raise what I believe is an API design discussion around Column Pinning, especially while v9 is still evolving.

I know issue #5986 discusses RTL support for column pinning. I think the underlying issue is broader than RTL, so I'd like to discuss the public API design itself rather than a specific RTL behavior.

---

The architectural issue

One of TanStack Table's greatest strengths is its headless design.

Most of the public API models table concepts rather than rendering implementation details:

• sorting
• filtering
• grouping
• selection
• column order
• column visibility
• row models
• etc.

These concepts are independent of how the table is ultimately rendered.

Column Pinning feels different.

The current API models pinned columns as physical sides:

columnPinning: {
  left: [...],
  right: [...],
}

But left and right are rendering/layout concepts.

From a headless library, I would expect the API to expose the logical table concept - pinning to the beginning or end of the table - while the rendering layer decides how those concepts map onto the physical layout.

In other words, the logical model seems like:

columnPinning: {
  start: [...],
  end: [...],
}

not:

columnPinning: {
  left: [...],
  right: [...],
}

---

Why this is more than a naming preference

If this were only about terminology, it probably would not be worth changing.

The real issue is that physical directions leak through the public API into application code.

Suppose an application supports dynamic language switching.

The user can switch between English (LTR) and Hebrew/Arabic (RTL) at runtime.

The logical behavior of the table should remain the same:

• Name should stay at the start of the table.
• 操作 should stay at the end of the table.

Users usually don't think:

Pin this column to the left side of the screen.

They think:

Keep this column at the beginning of the table.

or:

Keep the actions column at the end of the table.

Those are stable logical concepts, regardless of layout direction.

---

Example

Suppose I have this table in English:

| Name | Email | Phone | 操作 |

In LTR, I naturally want:

• Name pinned to the start
• 操作 pinned to the end

When switching to Hebrew or Arabic, I expect the table direction to flip:

| 操作 | Phone | Email | Name |

The logical pinning did not change.

Name is still pinned to the start.

操作 is still pinned to the end.

However, with the current API, the application has to translate that logical state into physical state.

In LTR:

left:  ["name"]
right: ["actions"]

In RTL:

right: ["name"]
left:  ["actions"]

So changing the writing direction requires changing the column pinning state, even though the logical table state did not actually change.

That feels like a sign that the state is modeled at the wrong level of abstraction.

---

The complexity goes beyond state

The rendering code also has to become direction-dependent.

In LTR:

row.getLeftVisibleCells()
row.getCenterVisibleCells()
row.getRightVisibleCells()

In RTL:

row.getRightVisibleCells()
row.getCenterVisibleCells()
row.getLeftVisibleCells()

It becomes even more complicated when users can pin and unpin columns interactively, because the application has to translate user actions between logical intent and physical state whenever the writing direction changes.

So every bidirectional application has to build an adapter layer on top of TanStack Table just to translate between:

• logical application state
• TanStack's physical pinning API
• physical rendering order

That feels like an implementation detail leaking through the public API into every bidirectional application.

---

Proposed API

Instead of:

columnPinning: {
  left: [],
  right: [],
}

use logical directions:

columnPinning: {
  start: [],
  end: [],
}

Likewise:

column.pin("start")
column.pin("end")

row.getStartVisibleCells()
row.getCenterVisibleCells()
row.getEndVisibleCells()

Applications could then always render:

row.getStartVisibleCells()
row.getCenterVisibleCells()
row.getEndVisibleCells()

regardless of whether the table is currently LTR or RTL.

That seems more consistent with the philosophy of a headless library.

This is also consistent with the existing getStart / getAfter API, which already describes offsets in logical row-axis terms rather than as getLeftOffset / getRightOffset. The current inconsistency is that the pinning state and position arguments are still physical (left / right), even though the underlying offset concept is naturally logical.

---

Why start/end is a better abstraction

Modern CSS has gone through a similar evolution.

Instead of relying only on physical properties such as:

• margin-left
• padding-right

CSS now also has logical properties such as:

• margin-inline-start
• padding-inline-end

because logical APIs compose much better with different writing directions.

I think Column Pinning has the same characteristic.

start and end describe the table concept.

left and right describe one possible physical implementation.

---

Why I think this should happen before v9

I realize this would be a breaking API change.

Normally I would avoid proposing that.

However, v9 is already introducing significant breaking changes, and this seems like a good opportunity to improve the API while v9 is still evolving.

After v9 is finalized, this would likely become much harder to change before the next major version.

The migration appears relatively straightforward:

left  -> start
right -> end

while the long-term API becomes:

• more semantic
• direction-independent
• simpler for bidirectional applications
• better aligned with the headless philosophy

---

I'd be happy to help

If the maintainers think this direction makes sense, I'd be happy to implement the change myself and open a PR.

Before investing the time, I'd like to know whether the maintainers think this direction is consistent with the goals for v9.

[KevinVandy]

I was originally against this, but it was well-written and pretty much convinced me. We already use the same language for column offsets for the same reason

[na-pel]

Thanks, Kevin. Glad to hear that.

That was exactly the connection I was hoping to make: getStart / getAfter already seem to express the offset model in logical row-axis terms, so aligning column pinning with the same logical language feels like a natural continuation rather than a separate RTL-specific feature.

If this direction sounds right for v9, I’d be happy to take a first pass at a PR.

Would you prefer a clean breaking change from left/right to start/end, or should I explore whether a limited compatibility layer is feasible, such as accepting left/right as deprecated aliases during the v9 transition?

[KevinVandy]

#6398

[na-pel]

Wow. That was incredibly fast!

Thank you so much for taking this seriously, implementing it end-to-end, and updating the docs as well. I really appreciate it.

This is exactly the kind of responsiveness that makes TanStack such a great ecosystem to work with.