> ## Documentation Index
> Fetch the complete documentation index at: https://learn.nextedy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Sort By

> The `sortBy` section of a Nextedy POWERSHEET sheet configuration defines the default client-side sort order for rows when the sheet loads. It supports multiple columns and custom sort directions.

export const LastReviewed = ({date}) => {
  if (!date) return null;
  const formatted = new Date(`${date}T00:00:00Z`).toLocaleDateString("en-US", {
    year: "numeric",
    month: "long",
    day: "numeric",
    timeZone: "UTC"
  });
  return <p className="mt-10 text-sm text-gray-400 dark:text-zinc-500 not-prose">
      Last reviewed on {formatted}
    </p>;
};

## sortBy Properties

| Property             | Type   | Default | Description                                                                                                                              |
| -------------------- | ------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `sortBy`             | array  | `[]`    | Array of sort definitions applied in order. The first entry is the primary sort; subsequent entries break ties.                          |
| `sortBy[].columnId`  | string | None    | **(required)** Dot-separated binding path to the column that should be sorted. Must match a column key defined in the `columns` section. |
| `sortBy[].direction` | string | `"asc"` | **(optional)** Sort direction. Supported values: `"asc"` (ascending), `"desc"` (descending).                                             |

## Sort Behavior

| Behavior                 | Description                                                                                                                    |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------ |
| Client-side              | Sorting is applied in the browser after data is loaded                                                                         |
| Multi-column             | Multiple sort entries are supported; order in the array determines priority                                                    |
| Default direction        | If `direction` is omitted, `"asc"` is used                                                                                     |
| Interactive override     | Users can click column headers to change sort direction at runtime                                                             |
| Default sort persistence | The configured `sortBy` is always re-applied as a secondary sort after user-initiated sorts to maintain hierarchical stability |

## Sort Flow

<Frame>
  <img src="https://mintcdn.com/none-17b4493f/-WiVljKlDztH36bB/powersheet/diagrams/reference/sheet-config/sortby/diagram-1.svg?fit=max&auto=format&n=-WiVljKlDztH36bB&q=85&s=97c30a6afe17450eed853bcca52581ed" alt="diagram" style={{ width: "520px", maxWidth: "100%" }} width="520" height="140" data-path="powersheet/diagrams/reference/sheet-config/sortby/diagram-1.svg" />
</Frame>

## Basic Sort

Sort by a single column in ascending order:

```yaml theme={null}
sortBy:
  - columnId: outlineNumber
    direction: asc
```

## Multi-Column Sort

Sort by primary column, then by secondary column for rows with equal primary values:

```yaml theme={null}
sortBy:
  - columnId: outlineNumber
    direction: asc
  - columnId: title
    direction: asc
```

## Descending Sort

```yaml theme={null}
sortBy:
  - columnId: severity
    direction: desc
```

## Column-Level Sort

Individual columns can also specify a default sort direction via the `sort` column property. This is applied in addition to the global `sortBy` configuration.

| Property         | Type   | Default | Description                                                                 |
| ---------------- | ------ | ------- | --------------------------------------------------------------------------- |
| `columns.*.sort` | string | None    | Default sort direction for this specific column. Values: `"asc"`, `"desc"`. |

```yaml theme={null}
columns:
  outlineNumber:
    title: "#"
    width: 80
    sort: asc
```

<Tip title="sortBy vs Column sort">
  Use the top-level `sortBy` for the primary sheet sort order. Use the column-level `sort` property when a specific column should always maintain a particular direction as a secondary sort criterion.
</Tip>

## Interactive Sort

Users can sort interactively in the sheet:

| Action                        | Result                                                 |
| ----------------------------- | ------------------------------------------------------ |
| Click column header sort icon | Sort by that column (toggles ascending/descending)     |
| `Ctrl+Click` column header    | Add column to existing multi-column sort               |
| Reset sort (toolbar)          | Remove user-applied sorts and restore `sortBy` default |

Sort state indicators appear in column headers showing the current sort direction. Multi-column sort shows small numbers indicating sort priority.

## Sort Type Behavior

| Column Type   | Sort Behavior                                   |
| ------------- | ----------------------------------------------- |
| Text (string) | Alphabetical sort                               |
| Enum          | Sort by enum value sequence, not alphabetically |
| Reference     | Sort by display value of the referenced entity  |
| Workflow      | Sort by transition display text                 |
| Custom render | Sort by the rendered display value              |

## Complete YAML Example

```yaml theme={null}
sortBy:
  - columnId: outlineNumber
    direction: asc

columns:
  outlineNumber:
    title: "#"
    width: 80
    sort: asc
  title:
    title: User Need
    width: 200
    hasFocus: true
  systemRequirements.systemRequirement.title:
    title: System Requirement
    width: 180
    columnGroup: sysReq
  systemRequirements.systemRequirement.severity:
    title: Severity
    width: 100
    columnGroup: sysReq

columnGroups:
  sysReq:
    groupName: System Requirements
    groupStyle: darkblue
    headerStyle: blue
    collapseTo: systemRequirements.systemRequirement.title

sources:
  - id: main
    title: RTM
    model: rtm
    query:
      from: UserNeed
      where: "type = 'UserNeed'"
    expand:
      - name: systemRequirements
        title: System Requirements
```

## Related Pages

* [Columns](/powersheet/reference/sheet-config/columns) -- the `sort` column-level property
* [Columns](/powersheet/reference/sheet-config/columns) -- column definitions and binding paths

***

<LastReviewed date="2026-07-02" />