> ## 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.

# Column Groups

> Column groups in Nextedy POWERSHEET visually organize related columns under shared header rows with styling and optional collapse behavior.

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>;
};

See also: [Columns](/powersheet/reference/sheet-config/columns) | [Styles](/powersheet/reference/sheet-config/styles)

## Column Group Structure

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

In the rendered sheet, column groups appear as a second header row above the regular column headers, merging cells across all columns that share the same `columnGroup`. The group header includes the group name and, when `collapseTo` is set, a toggle button to expand or collapse the group.

<Frame>
  <img src="https://mintcdn.com/none-17b4493f/KGc-UcQNrDeK-NiS/powersheet/images/48001275923/8.png?fit=max&auto=format&n=KGc-UcQNrDeK-NiS&q=85&s=772938271ff07296500194a9ba766f70" alt="Powersheet header showing two stacked group headers (Epics and User Stories) above the regular column headers, with collapse toggles on each group and a Test Cases sub-group inside User Stories" style={{ maxWidth: "720px", width: "100%" }} width="2772" height="280" data-path="powersheet/images/48001275923/8.png" />
</Frame>

## Column Group Properties

| Name          | Type     | Default      | Description                                                                                                                                                  |
| ------------- | -------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `groupName`   | `string` | Required     | Display name for the column group header. Shown in the merged group header row.                                                                              |
| `groupStyle`  | `string` | None (white) | Color identifier applied to the grouped columns' background. Must be a predefined style name or a custom style defined in the `styles` section.              |
| `headerStyle` | `string` | None (white) | Color identifier applied to all sub-headers of the group. Can be overridden by `header.style` defined on individual columns.                                 |
| `collapseTo`  | `string` | None         | Binding path of the column to display when the group is collapsed. If the specified column is hidden, the last visible column in the group is shown instead. |

<Tip title="Collapse behavior">
  When `collapseTo` is not specified, the group does not provide a collapse option. The collapse toggle button appears in the group header only when `collapseTo` is configured.
</Tip>

## Defining Column Groups

Column groups are defined in the top-level `columnGroups` section. Each key is a group ID referenced by individual columns:

```yaml theme={null}
columnGroups:
  requirements:
    groupName: Requirements
    groupStyle: darkblue
    headerStyle: blue
    collapseTo: title

  testing:
    groupName: Testing
    groupStyle: darkgreen
    headerStyle: green
    collapseTo: validationTestCases.validationTestCase
```

## Assigning Columns to Groups

Add the `columnGroup` property to individual column definitions, referencing the group ID:

```yaml theme={null}
columns:
  title:
    title: Title
    width: 200
    columnGroup: requirements

  severity:
    title: Severity
    width: 100
    columnGroup: requirements

  validationTestCases.validationTestCase:
    title: Validation Tests
    width: 180
    columnGroup: testing
    multiItem: true
```

## Predefined Styles for Groups

Use any of the predefined style names for `groupStyle` and `headerStyle`:

| Style Name    | Text Color  | Background Color |
| ------------- | ----------- | ---------------- |
| `none`        | none        | none             |
| `boldTitle`   | --          | --               |
| `darkgrey`    | `grey700`   | `grey200`        |
| `grey`        | `grey700`   | `grey100`        |
| `darkred`     | `red700`    | `red200`         |
| `red`         | `red700`    | `red100`         |
| `darkorange`  | `orange700` | `orange200`      |
| `orange`      | `orange700` | `orange100`      |
| `darkgreen`   | `green700`  | `green200`       |
| `green`       | `green700`  | `green100`       |
| `lightgreen`  | `green700`  | `primaryalt100`  |
| `darkblue`    | `blue700`   | `blue200`        |
| `blue`        | `blue700`   | `blue100`        |
| `lightblue`   | `blue700`   | `teal100`        |
| `darkteal`    | `teal700`   | `teal200`        |
| `teal`        | `teal700`   | `teal100`        |
| `darkpurple`  | `purple700` | `purple200`      |
| `purple`      | `purple700` | `purple100`      |
| `lightpurple` | `purple700` | `primary100`     |

See [Styles](/powersheet/reference/sheet-config/styles) for the full style reference with color tokens.

## Collapse and Expand

When a group is configured with `collapseTo`, users can toggle the group between expanded and collapsed states:

* **Expanded**: All columns in the group are visible
* **Collapsed**: Only the `collapseTo` column is visible; other columns are hidden

The collapse toggle button appears in the group header row.

```yaml theme={null}
columnGroups:
  sysReq:
    groupName: System Requirements
    groupStyle: darkblue
    headerStyle: blue
    collapseTo: systemRequirements.systemRequirement.title
```

<Warning title="Collapse target fallback">
  If the column specified in `collapseTo` is hidden (not visible), the last visible column in the group is used as the collapse target instead.
</Warning>

## Ungrouped Columns

Columns without an explicit `columnGroup` assignment display a blank group header. The two-row header structure (group row + column row) is maintained consistently whether groups are defined or not.

## Exporting Column Groups

Column group headers are exported to Excel when using the export feature. Merged cells span all columns in the group, displaying the group name once in the exported file.

## Complete YAML Example

```yaml theme={null}
columnGroups:
  userNeed:
    groupName: User Needs
    groupStyle: darkpurple
    headerStyle: purple

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

  testing:
    groupName: Testing
    groupStyle: darkgreen
    headerStyle: green
    collapseTo: validationTestCases.validationTestCase

columns:
  outlineNumber:
    title: "#"
    width: 80

  title:
    title: User Need
    width: 200
    hasFocus: true
    columnGroup: userNeed

  severity:
    title: Severity
    width: 100
    columnGroup: userNeed

  systemRequirements.systemRequirement.title:
    title: Sys Req Title
    width: 200
    columnGroup: sysReq
    hasFocus: true

  systemRequirements.systemRequirement.severity:
    title: Sys Req Severity
    width: 100
    columnGroup: sysReq

  validationTestCases.validationTestCase:
    title: Validation Tests
    width: 180
    multiItem: true
    display: title
    columnGroup: testing

  systemRequirements.systemRequirement.verificationTestCases.verificationTestCase:
    title: Verification Tests
    width: 180
    multiItem: true
    display: title
    columnGroup: testing

styles:
  readOnlyStyle:
    backgroundColor: grey100

formatters:
  readonly:
    - expression: 'true'
      style: readOnlyStyle

sources:
  - id: rtm
    model: rtm
    query:
      from: UserNeed
    expand:
      - name: systemRequirements
        title: System Requirements
        expand:
          - name: designRequirements
            title: Design Requirements
          - name: verificationTestCases
            title: Verification Tests
      - name: validationTestCases
        title: Validation Tests
```

***

**Related pages:** [Columns](/powersheet/reference/sheet-config/columns) | [Styles](/powersheet/reference/sheet-config/styles) | [Views](/powersheet/reference/sheet-config/views)

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