Add multi-column sorting with stack-based behavior

[lucharo]

Summary

Implements multi-column sorting for marimo tables with stack-based behavior. Clicking a column sort moves it to the highest priority (end of sort array). Clicking the same direction again removes that sort. Visual indicators show sort priority (1, 2, 3...) in dropdown menus. "Clear sort" button adapts to "Clear all sorts" when multiple columns are sorted.

Backend uses list[SortArgs] where each SortArgs contains by: ColumnName and descending: bool. Frontend sends sort state as [{by: string, descending: boolean}]. Compatible with latest upstream table manager refactoring (IbisTableManager now extends NarwhalsTableManager).

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
marimo-docs	Ready	Preview	Comment	Oct 6, 2025 5:24pm

[Light2Dark]

and here, list[tuple[ColumnName, bool]]

[Light2Dark]

maybe we can simplify/optimize this, it's difficult to read.

[Light2Dark]

            first_column = next(iter(data_dict.values()))
            num_rows = len(first_column)
            indices = list(range(num_rows))

I'm not sure if sorting for default_table is expensive. If not, then this looks fine.
If you do see optimizations, then it would be nice to add.

[lucharo]

Hey @Light2Dark, thanks for the quick review. I submitted this PR as a draft, as I still need some help with the front end that I can't quite get. I followed your comments and changed the sorting elements to tuples, which is easier to reason about as you suggested!

I also need your feedback/help on how to best present the multisort. Initially, the multi-sort was enabled by clicking the Shift key, but then I thought that'd be too implicit and doesn't really resonate with the rest of marimo's design and might even clash with some users' keyboard shortcuts. So I've settled for including a checkbox for the currently selected sorted state (descending/ascending for any given column and including an explicit "Remove sort" button), but the design is really subpar. Front-end is not my thing.

I'm hitting a union type issue I can't quite get my head around, see below for what this all looks like and the error I am getting (all in port 3000 after running make dev):

Error calling function search: Value '[{'by': 'Name', 'descending': False}]' does not fit any type of the union

[Light2Dark]

I tried out the branch, you may need to stop and run the make dev server again for it to catch the new API. I would remove the checkbox too, I don't think it's necessary. What might be nice is to have the Asc / Desc icon be clickable to remove the sort directly, instead of opening the menu. But we can do this in follow-ups.

[Light2Dark]

this looks great! small review

[Light2Dark]

Hey Lucharo, I think this will be a nicer refactor, you can use the column.toggleSorting to achieve what you want instead of manually setting the table sort

export function renderSorts<TData, TValue>(
  column: Column<TData, TValue>,
  table?: Table<TData>,
) {
  if (!column.getCanSort()) {
    return null;
  }

  const sortDirection = column.getIsSorted();
  const sortingIndex = column.getSortIndex();

  const sortingState = table?.getState().sorting;
  const hasMultiSort = sortingState?.length && sortingState.length > 1;

  const renderSortIndex = () => {
    return (
      <span className="ml-auto text-xs font-medium">{sortingIndex + 1}</span>
    );
  };

  const renderClearSort = () => {
    if (!sortDirection) {
      return null;
    }

    if (!hasMultiSort) {
      // render clear sort for this column
      return (
        <DropdownMenuItem onClick={() => column.clearSorting()}>
          <ChevronsUpDown className="mo-dropdown-icon" />
          Clear sort
        </DropdownMenuItem>
      );
    }

    // render clear sort for all columns
    return (
      <DropdownMenuItem onClick={() => table?.resetSorting()}>
        <ChevronsUpDown className="mo-dropdown-icon" />
        Clear all sorts
      </DropdownMenuItem>
    );
  };

  const toggleSort = (direction: SortDirection) => {
    // Clear sort if clicking the same direction
    if (sortDirection === direction) {
      column.clearSorting();
    } else {
      // Toggle sort direction
      const descending = direction === "desc";
      column.toggleSorting(descending, true);
    }
  };

  return (
    <>
      <DropdownMenuItem
        onClick={() => toggleSort("asc")}
        className={sortDirection === "asc" ? "bg-accent" : ""}
      >
        <AscIcon className="mo-dropdown-icon" />
        Asc
        {sortDirection === "asc" && renderSortIndex()}
      </DropdownMenuItem>
      <DropdownMenuItem
        onClick={() => toggleSort("desc")}
        className={sortDirection === "desc" ? "bg-accent" : ""}
      >
        <DescIcon className="mo-dropdown-icon" />
        Desc
        {sortDirection === "desc" && renderSortIndex()}
      </DropdownMenuItem>
      {renderClearSort()}
      <DropdownMenuSeparator />
    </>
  );
}

[Light2Dark]

            first_column = next(iter(data_dict.values()))
            num_rows = len(first_column)
            indices = list(range(num_rows))

I'm not sure if sorting for default_table is expensive. If not, then this looks fine.
If you do see optimizations, then it would be nice to add.

[lucharo]

could you re-run this step @Light2Dark , I think it was a network error: https://github.com/marimo-team/marimo/actions/runs/18248342628/job/51959424513?pr=6257

[Light2Dark]

re-running, @lucharo there are some failing tests

[mscolnick]

maybe we should just filter to the columns that do exist, then sort with those. otherwise the UI may be inconsistent (it says its sorting, but it is not)

[mscolnick]

same here, maybe just filter to valid/sortable columns

[Light2Dark]

lgtm! thanks for the contribution

[lucharo]

CI finally passed! Thanks @Light2Dark for the review and help throughout this PR! 🙏🏼