From 9e694ef052e940161f8e745d69d6541f2d4cc570 Mon Sep 17 00:00:00 2001
From: Sherzod Baxodirov <sherzod.baxodirov@constructor.io>
Date: Mon, 10 Aug 2026 18:17:11 +0500
Subject: [PATCH 1/4] feat: implement FilterOptionsList component

---
 .../FilterOption/FilterOption.test.tsx        |  20 ++
 .../FilterOptionsList.test.tsx                | 284 ++++++++++++++++++
 src/components/filter-option.tsx              |   6 +-
 src/components/filter-options-list.tsx        | 139 +++++++++
 src/index.ts                                  |   7 +
 .../FilterOptionsList.stories.tsx             | 225 ++++++++++++++
 6 files changed, 679 insertions(+), 2 deletions(-)
 create mode 100644 spec/components/FilterOptionsList/FilterOptionsList.test.tsx
 create mode 100644 src/components/filter-options-list.tsx
 create mode 100644 src/stories/components/FilterOptionsList/FilterOptionsList.stories.tsx

diff --git a/spec/components/FilterOption/FilterOption.test.tsx b/spec/components/FilterOption/FilterOption.test.tsx
index eed8a41..4ab16ad 100644
--- a/spec/components/FilterOption/FilterOption.test.tsx
+++ b/spec/components/FilterOption/FilterOption.test.tsx
@@ -207,6 +207,26 @@ describe('FilterOption component', () => {
       );
       expect(screen.queryByText('Red')).not.toBeInTheDocument();
     });
+
+    test('render-prop reactNode receives children so nested content can be re-emitted', () => {
+      render(
+        <FilterOption
+          id='test-1'
+          optionValue='red'
+          displayValue='Red'
+          componentOverrides={{
+            reactNode: (props) => <li data-testid='custom-override'>{props.children}</li>,
+          }}
+          onChange={() => {}}>
+          <span data-testid='nested-child'>Nested</span>
+        </FilterOption>,
+      );
+      const override = screen.getByTestId('custom-override');
+      expect(override).toBeInTheDocument();
+      expect(screen.getByTestId('nested-child')).toBeInTheDocument();
+      // The nested child is inside the overridden node, not lost.
+      expect(override).toContainElement(screen.getByTestId('nested-child'));
+    });
   });
 
   describe('CSS classes', () => {
diff --git a/spec/components/FilterOptionsList/FilterOptionsList.test.tsx b/spec/components/FilterOptionsList/FilterOptionsList.test.tsx
new file mode 100644
index 0000000..17c5cab
--- /dev/null
+++ b/spec/components/FilterOptionsList/FilterOptionsList.test.tsx
@@ -0,0 +1,284 @@
+import React from 'react';
+import { render, screen, cleanup, fireEvent } from '@testing-library/react';
+import { describe, test, expect, afterEach, vi } from 'vitest';
+import FilterOptionsList, { type FilterOptionData } from '@/components/filter-options-list';
+
+// A 3-level fixture reused across tests.
+const nestedOptions: FilterOptionData[] = [
+  {
+    id: 'l0',
+    optionValue: 'level-0',
+    displayValue: 'Level 0',
+    displayCountValue: '100',
+    hierarchies: [
+      {
+        id: 'l1',
+        optionValue: 'level-1',
+        displayValue: 'Level 1',
+        isChecked: true,
+        hierarchies: [
+          {
+            id: 'l2',
+            optionValue: 'level-2',
+            displayValue: 'Level 2',
+          },
+        ],
+      },
+    ],
+  },
+];
+
+const flatOptions: FilterOptionData[] = [
+  { id: 'a', optionValue: 'a', displayValue: 'Alpha' },
+  { id: 'b', optionValue: 'b', displayValue: 'Bravo' },
+  { id: 'c', optionValue: 'c', displayValue: 'Charlie' },
+];
+
+describe('FilterOptionsList component', () => {
+  afterEach(() => {
+    cleanup();
+  });
+
+  describe('flat data', () => {
+    test('renders all options as sibling rows', () => {
+      render(<FilterOptionsList options={flatOptions} onChange={() => { }} />);
+      expect(screen.getByText('Alpha')).toBeInTheDocument();
+      expect(screen.getByText('Bravo')).toBeInTheDocument();
+      expect(screen.getByText('Charlie')).toBeInTheDocument();
+      expect(screen.getAllByRole('listitem')).toHaveLength(3);
+    });
+
+    test('renders a single top-level list without indentation', () => {
+      const { container } = render(<FilterOptionsList options={flatOptions} onChange={() => { }} />);
+      const lists = container.querySelectorAll('[data-slot="filter-options-list"]');
+      expect(lists).toHaveLength(1);
+      expect(lists[0].classList.contains('cio:pl-4')).toBeFalsy();
+    });
+  });
+
+  describe('hierarchical rendering', () => {
+    test('recurses into hierarchies at every depth', () => {
+      render(<FilterOptionsList options={nestedOptions} onChange={() => { }} />);
+      // A leaf several levels deep is present.
+      expect(screen.getByText('Level 0')).toBeInTheDocument();
+      expect(screen.getByText('Level 1')).toBeInTheDocument();
+      expect(screen.getByText('Level 2')).toBeInTheDocument();
+    });
+
+    test('renders a nested list per level with a data-slot', () => {
+      const { container } = render(
+        <FilterOptionsList options={nestedOptions} onChange={() => { }} />,
+      );
+      // Root + Level 0's children + Level 1's children = 3 lists.
+      expect(container.querySelectorAll('[data-slot="filter-options-list"]')).toHaveLength(3);
+    });
+
+    test('indents nested lists but not the root', () => {
+      const { container } = render(
+        <FilterOptionsList options={nestedOptions} onChange={() => { }} />,
+      );
+      const lists = Array.from(container.querySelectorAll('[data-slot="filter-options-list"]'));
+      const indented = lists.filter((el) => el.classList.contains('cio:pl-4'));
+      // Every list except the root is indented.
+      expect(indented).toHaveLength(lists.length - 1);
+      expect(lists[0].classList.contains('cio:pl-4')).toBeFalsy();
+    });
+
+    test('parent rows with children get cio:flex-col to stack the nested list below', () => {
+      render(<FilterOptionsList options={nestedOptions} onChange={() => { }} />);
+      const parentRow = screen.getByText('Level 0').closest('li');
+      expect(parentRow?.classList.contains('cio:flex-col')).toBeTruthy();
+      const leafRow = screen.getByText('Level 2').closest('li');
+      expect(leafRow?.classList.contains('cio:flex-col')).toBeFalsy();
+    });
+  });
+
+  describe('selection at each depth', () => {
+    test.each([
+      ['Level 0', 'level-0'],
+      ['Level 1', 'level-1'],
+      ['Level 2', 'level-2'],
+    ])('calls onChange with the option value when %s is clicked', (label, value) => {
+      const handleChange = vi.fn();
+      render(<FilterOptionsList options={nestedOptions} onChange={handleChange} />);
+      fireEvent.click(screen.getByText(label));
+      expect(handleChange).toHaveBeenCalledWith(value);
+    });
+
+    test('reflects isChecked state per depth', () => {
+      render(<FilterOptionsList options={nestedOptions} onChange={() => { }} />);
+      // Level 1 is the only pre-checked node.
+      expect(screen.getByText('Level 0').closest('li')?.querySelector('input')).not.toBeChecked();
+      expect(screen.getByText('Level 1').closest('li')?.querySelector('input')).toBeChecked();
+      expect(screen.getByText('Level 2').closest('li')?.querySelector('input')).not.toBeChecked();
+    });
+  });
+
+  describe('componentOverrides', () => {
+    test('list-level reactNode replaces the entire list', () => {
+      render(
+        <FilterOptionsList
+          options={flatOptions}
+          onChange={() => { }}
+          componentOverrides={{
+            reactNode: <ul data-testid='custom-list'>Custom list</ul>,
+          }}
+        />,
+      );
+      expect(screen.getByTestId('custom-list')).toBeInTheDocument();
+      expect(screen.queryByText('Alpha')).not.toBeInTheDocument();
+    });
+
+    test('filterOption slot overrides every row', () => {
+      render(
+        <FilterOptionsList
+          options={flatOptions}
+          onChange={() => { }}
+          componentOverrides={{
+            filterOption: {
+              reactNode: <li data-testid='custom-row'>Custom row</li>,
+            },
+          }}
+        />,
+      );
+      expect(screen.getAllByTestId('custom-row')).toHaveLength(3);
+      expect(screen.queryByText('Alpha')).not.toBeInTheDocument();
+    });
+
+    test('filterOption function targets a single option, leaving others at default', () => {
+      render(
+        <FilterOptionsList
+          options={flatOptions}
+          onChange={() => { }}
+          componentOverrides={{
+            filterOption: (option) =>
+              option.id === 'b'
+                ? { reactNode: <li data-testid='only-bravo'>Custom Bravo</li> }
+                : undefined,
+          }}
+        />,
+      );
+      // Only Bravo is overridden; Alpha and Charlie render normally.
+      expect(screen.getByTestId('only-bravo')).toBeInTheDocument();
+      expect(screen.queryByText('Bravo')).not.toBeInTheDocument();
+      expect(screen.getByText('Alpha')).toBeInTheDocument();
+      expect(screen.getByText('Charlie')).toBeInTheDocument();
+    });
+
+    test('filterOption function targets an option at depth', () => {
+      render(
+        <FilterOptionsList
+          options={nestedOptions}
+          onChange={() => { }}
+          componentOverrides={{
+            filterOption: (option) =>
+              option.id === 'l2'
+                ? { reactNode: <li data-testid='deep-override'>Deep</li> }
+                : undefined,
+          }}
+        />,
+      );
+      // The depth-2 leaf is overridden; its ancestors render normally.
+      expect(screen.getByTestId('deep-override')).toBeInTheDocument();
+      expect(screen.queryByText('Level 2')).not.toBeInTheDocument();
+      expect(screen.getByText('Level 0')).toBeInTheDocument();
+      expect(screen.getByText('Level 1')).toBeInTheDocument();
+    });
+
+    test('render-prop override on a parent row re-emits its nested children', () => {
+      const { container } = render(
+        <FilterOptionsList
+          options={nestedOptions}
+          onChange={() => { }}
+          componentOverrides={{
+            filterOption: (option) =>
+              option.id === 'l0'
+                ? {
+                  reactNode: (props) => (
+                    <li data-testid='parent-override'>
+                      {props.displayValue}
+                      {props.children}
+                    </li>
+                  ),
+                }
+                : undefined,
+          }}
+        />,
+      );
+      // The parent row is overridden but its subtree survives via props.children.
+      expect(screen.getByTestId('parent-override')).toBeInTheDocument();
+      expect(screen.getByText('Level 1')).toBeInTheDocument();
+      expect(screen.getByText('Level 2')).toBeInTheDocument();
+      // Nested list is still rendered beneath the overridden parent.
+      expect(container.querySelectorAll('[data-slot="filter-options-list"]')).toHaveLength(3);
+    });
+  });
+
+  describe('empty hierarchies guard', () => {
+    test('a node with an empty hierarchies array renders no nested list and no flex-col', () => {
+      const options: FilterOptionData[] = [
+        { id: 'leaf', optionValue: 'leaf', displayValue: 'Leaf', hierarchies: [] },
+      ];
+      const { container } = render(<FilterOptionsList options={options} onChange={() => { }} />);
+      expect(container.querySelectorAll('[data-slot="filter-options-list"]')).toHaveLength(1);
+      expect(
+        screen.getByText('Leaf').closest('li')?.classList.contains('cio:flex-col'),
+      ).toBeFalsy();
+    });
+  });
+
+  describe('conventions', () => {
+    test('has data-slot attribute on the root list', () => {
+      render(<FilterOptionsList options={flatOptions} onChange={() => { }} />);
+      expect(screen.getByRole('list')).toHaveAttribute('data-slot', 'filter-options-list');
+    });
+
+    test('has cio-filter-options-list class', () => {
+      render(<FilterOptionsList options={flatOptions} onChange={() => { }} />);
+      expect(screen.getByRole('list').classList.contains('cio-filter-options-list')).toBeTruthy();
+    });
+
+    test('merges custom className onto the root list', () => {
+      render(
+        <FilterOptionsList options={flatOptions} className='my-custom-class' onChange={() => { }} />,
+      );
+      expect(screen.getByRole('list').classList.contains('my-custom-class')).toBeTruthy();
+    });
+
+    test('spreads data-* attributes onto the root list', () => {
+      render(
+        <FilterOptionsList
+          options={flatOptions}
+          data-testid='my-list'
+          data-facet='color'
+          onChange={() => { }}
+        />,
+      );
+      expect(screen.getByTestId('my-list').dataset.facet).toBe('color');
+    });
+  });
+
+  describe('unique-id contract', () => {
+    test('rows across branches toggle only their own input', () => {
+      const handleChange = vi.fn();
+      const options: FilterOptionData[] = [
+        {
+          id: 'branch-a',
+          optionValue: 'branch-a',
+          displayValue: 'Branch A',
+          hierarchies: [{ id: 'a-child', optionValue: 'a-child', displayValue: 'A Child' }],
+        },
+        {
+          id: 'branch-b',
+          optionValue: 'branch-b',
+          displayValue: 'Branch B',
+          hierarchies: [{ id: 'b-child', optionValue: 'b-child', displayValue: 'B Child' }],
+        },
+      ];
+      render(<FilterOptionsList options={options} onChange={handleChange} />);
+      fireEvent.click(screen.getByText('A Child'));
+      expect(handleChange).toHaveBeenCalledTimes(1);
+      expect(handleChange).toHaveBeenCalledWith('a-child');
+    });
+  });
+});
diff --git a/src/components/filter-option.tsx b/src/components/filter-option.tsx
index 627f91b..13b7558 100644
--- a/src/components/filter-option.tsx
+++ b/src/components/filter-option.tsx
@@ -2,7 +2,7 @@ import React, { ReactNode } from 'react';
 import { cn, RenderPropsWrapper } from '@/utils';
 import { ComponentOverrideProps, IncludeComponentOverrides } from '@/types';
 const baseClasses =
-  'cio-components cio-filter-option cio-filter-multiple-option cio:group cio:cursor-pointer cio:flex cio:list-none cio:text-base cio:hover:bg-neutral-100 cio:hover:rounded';
+  'cio-components cio-filter-option cio-filter-multiple-option cio:flex cio:list-none cio:text-base';
 
 export interface FilterOptionProps
   extends Omit<React.ComponentProps<'li'>, 'onChange' | 'children'>,
@@ -55,6 +55,7 @@ export default function FilterOption({
       checkboxPosition,
       startContent,
       className,
+      children,
     }),
     [
       props,
@@ -67,6 +68,7 @@ export default function FilterOption({
       checkboxPosition,
       startContent,
       className,
+      children,
     ],
   );
 
@@ -90,7 +92,7 @@ export default function FilterOption({
       <li data-slot='filter-option' className={cn(baseClasses, className)} {...props}>
         <label
           htmlFor={id}
-          className='cio-filter-option-label cio:text-sm cio:flex cio:flex-row cio:items-center cio:cursor-pointer cio:grow cio:p-1'>
+          className='cio-filter-option-label cio:group cio:text-sm cio:flex cio:flex-row cio:items-center cio:cursor-pointer cio:grow cio:p-1 cio:hover:bg-neutral-100 cio:hover:rounded'>
           <input
             type='checkbox'
             id={id}
diff --git a/src/components/filter-options-list.tsx b/src/components/filter-options-list.tsx
new file mode 100644
index 0000000..45ee035
--- /dev/null
+++ b/src/components/filter-options-list.tsx
@@ -0,0 +1,139 @@
+import React from 'react';
+import { cn, RenderPropsWrapper } from '@/utils';
+import { ComponentOverrideProps, IncludeComponentOverrides } from '@/types';
+import FilterOption, {
+  type FilterOptionProps,
+  type FilterOptionOverrides,
+} from '@/components/filter-option';
+
+const baseClasses =
+  'cio-components cio-filter-options-list cio:list-none cio:p-0 cio:m-0 cio:flex cio:flex-col';
+
+/**
+ * A single option in a {@link FilterOptionsList}. Self-similar: an option can nest
+ * child options under `hierarchies`, which are rendered nested and indented. The shape
+ * is intentionally data-agnostic.
+ *
+ * Note: `id`s must be unique across the entire tree — `FilterOption` uses `id` for its
+ * `<input id>` / `<label htmlFor>` pair, so duplicate ids across branches break label
+ * association.
+ */
+export interface FilterOptionData
+  extends Pick<
+    FilterOptionProps,
+    'id' | 'optionValue' | 'displayValue' | 'displayCountValue' | 'isChecked' | 'startContent'
+  > {
+  /** Child options — rendered nested and indented. Omit (or leave empty) for a leaf row. */
+  hierarchies?: FilterOptionData[];
+}
+
+export interface FilterOptionsListProps
+  extends Omit<React.ComponentProps<'ul'>, 'onChange' | 'children'>,
+    IncludeComponentOverrides<FilterOptionsListOverrides> {
+  /**
+   * Options to render. Each option's `hierarchies` are recursed into, nesting + indenting
+   * each level; hierarchy is driven entirely by the data, so options without `hierarchies`
+   * render as a flat list.
+   */
+  options: FilterOptionData[];
+  /** Callback when any option's selection changes; receives the option's `optionValue` */
+  onChange: (value: string) => void;
+  /** Position of each option's checkbox. Forwarded to every `FilterOption`. */
+  checkboxPosition?: FilterOptionProps['checkboxPosition'];
+}
+
+/**
+ * Row-level override for a {@link FilterOptionsList}. Either:
+ * - an object applied to **every** `FilterOption` row at every depth, or
+ * - a function called per option, returning the overrides for that specific row (or
+ *   `undefined`/no `reactNode` to leave the row at its default). Use this to target a
+ *   single option — e.g. `(option) => option.id === 'x' ? {...} : undefined`.
+ *
+ * Note: a `filterOption.reactNode` render-prop function receives `props.children` — the
+ * row's nested list — so hierarchical rows can be overridden without dropping their
+ * `hierarchies`; re-emit `{props.children}` to keep nesting. A **static** `reactNode`
+ * (fixed JSX) has nowhere to receive children and so renders without them.
+ */
+export type FilterOptionOverride =
+  | FilterOptionOverrides
+  | ((option: FilterOptionData) => FilterOptionOverrides | undefined);
+
+export type FilterOptionsListOverrides = ComponentOverrideProps<FilterOptionsListProps> & {
+  filterOption?: FilterOptionOverride;
+};
+
+/**
+ * Presentational, recursive hierarchical filter list. Renders an `options` array as
+ * `FilterOption` rows, recursing into each option's `hierarchies` and reusing
+ * `FilterOption`'s `children` slot for nesting — so a flat list is just options with no
+ * `hierarchies`. Fully controlled: selection state comes in via each option's `isChecked`,
+ * and changes flow out via `onChange`.
+ */
+export default function FilterOptionsList(props: FilterOptionsListProps) {
+  return <FilterOptionsListInner {...props} nested={false} />;
+}
+
+/**
+ * Internal recursive renderer. The private `nested` flag (root vs. descendant) is kept
+ * off the public component so it never surfaces in the prop surface / autodocs; indentation
+ * compounds automatically via DOM nesting, so a boolean is all that's needed.
+ */
+function FilterOptionsListInner({
+  options,
+  onChange,
+  checkboxPosition,
+  componentOverrides,
+  className,
+  nested,
+  ...props
+}: FilterOptionsListProps & { nested: boolean }) {
+  const renderProps = React.useMemo(
+    () => ({
+      ...props,
+      options,
+      onChange,
+      checkboxPosition,
+      className,
+    }),
+    [props, options, onChange, checkboxPosition, className],
+  );
+
+  return (
+    <RenderPropsWrapper props={renderProps} override={componentOverrides?.reactNode}>
+      <ul
+        data-slot='filter-options-list'
+        className={cn(baseClasses, nested && 'cio:pl-4', className)}
+        {...props}>
+        {options.map((option) => {
+          const { hierarchies, ...optionProps } = option;
+          const hasChildren = !!hierarchies?.length;
+          const filterOption = componentOverrides?.filterOption;
+          const rowOverride =
+            typeof filterOption === 'function' ? filterOption(option) : filterOption;
+
+          return (
+            <FilterOption
+              key={option.id}
+              {...optionProps}
+              onChange={onChange}
+              checkboxPosition={checkboxPosition}
+              componentOverrides={rowOverride}
+              className={hasChildren ? 'cio:flex-col' : undefined}>
+              {hasChildren && (
+                <FilterOptionsListInner
+                  nested
+                  options={hierarchies}
+                  onChange={onChange}
+                  checkboxPosition={checkboxPosition}
+                  // Propagate only the row-level override — NOT the list-level `reactNode`,
+                  // which would replace each nested list wholesale and break recursion.
+                  componentOverrides={{ filterOption }}
+                />
+              )}
+            </FilterOption>
+          );
+        })}
+      </ul>
+    </RenderPropsWrapper>
+  );
+}
diff --git a/src/index.ts b/src/index.ts
index 65b65a1..6203a98 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -6,6 +6,7 @@ export { default as Carousel } from '@/components/carousel';
 export { default as Chip } from '@/components/chip';
 export { default as FilterOption } from '@/components/filter-option';
 export { default as FilterOptionVisual } from '@/components/filter-option--visual';
+export { default as FilterOptionsList } from '@/components/filter-options-list';
 export { RenderPropsWrapper, CIO_EVENTS, dispatchCioEvent } from '@/utils';
 
 // Hooks
@@ -21,4 +22,10 @@ export type { BadgeVariants, BadgeOverrides, BadgeProps } from '@/components/bad
 export type { ChipVariants, ChipOverrides, ChipProps } from '@/components/chip';
 export type { FilterOptionOverrides, FilterOptionProps } from '@/components/filter-option';
 export type { FilterOptionVisualProps } from '@/components/filter-option--visual';
+export type {
+  FilterOptionsListProps,
+  FilterOptionsListOverrides,
+  FilterOptionOverride,
+  FilterOptionData,
+} from '@/components/filter-options-list';
 export * from '@/types';
diff --git a/src/stories/components/FilterOptionsList/FilterOptionsList.stories.tsx b/src/stories/components/FilterOptionsList/FilterOptionsList.stories.tsx
new file mode 100644
index 0000000..e670f9a
--- /dev/null
+++ b/src/stories/components/FilterOptionsList/FilterOptionsList.stories.tsx
@@ -0,0 +1,225 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import FilterOptionsList, {
+  type FilterOptionData,
+  type FilterOptionsListOverrides,
+} from '../../../components/filter-options-list';
+
+const meta = {
+  title: 'Components/FilterOptionsList',
+  component: FilterOptionsList,
+  parameters: {
+    layout: 'centered',
+  },
+  tags: ['autodocs'],
+  args: {
+    onChange: () => { },
+  },
+  argTypes: {
+    checkboxPosition: {
+      control: 'radio',
+      options: ['left', 'right', 'none'],
+    },
+  },
+} satisfies Meta<typeof FilterOptionsList>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// Note: some editors may flag the fixtures below with a false "missing properties
+// (isChecked, startContent)" error. `src/stories/**` is excluded from every tsconfig, so the
+// TS server type-checks these files in an inferred project that ignores the `@/*` path alias
+// and mis-resolves `FilterOptionData`'s optional fields. It is IDE-only — `tsc` and the build
+// pass clean, and Vite compiles Storybook, not tsc.
+
+// A multi-level fixture with counts and pre-selected options at different depths.
+const hierarchicalOptions: FilterOptionData[] = [
+  {
+    id: 'apparel',
+    optionValue: 'apparel',
+    displayValue: 'Apparel',
+    displayCountValue: '1240',
+    hierarchies: [
+      {
+        id: 'apparel-mens',
+        optionValue: 'apparel/mens',
+        displayValue: "Men's",
+        displayCountValue: '540',
+        hierarchies: [
+          {
+            id: 'apparel-mens-shirts',
+            optionValue: 'apparel/mens/shirts',
+            displayValue: 'Shirts',
+            displayCountValue: '210',
+          },
+          {
+            id: 'apparel-mens-pants',
+            optionValue: 'apparel/mens/pants',
+            displayValue: 'Pants',
+            displayCountValue: '330',
+            isChecked: true,
+          },
+        ],
+      },
+      {
+        id: 'apparel-women',
+        optionValue: 'apparel/women',
+        displayValue: "Women's",
+        displayCountValue: '700',
+        hierarchies: [
+          {
+            id: 'apparel-women-dresses',
+            optionValue: 'apparel/women/dresses',
+            displayValue: 'Dresses',
+            displayCountValue: '400',
+          },
+        ],
+      },
+    ],
+  },
+  {
+    id: 'electronics',
+    optionValue: 'electronics',
+    displayValue: 'Electronics',
+    displayCountValue: '860',
+    isChecked: true,
+    hierarchies: [
+      {
+        id: 'electronics-phones',
+        optionValue: 'electronics/phones',
+        displayValue: 'Phones',
+        displayCountValue: '312',
+      },
+      {
+        id: 'electronics-laptops',
+        optionValue: 'electronics/laptops',
+        displayValue: 'Laptops',
+        displayCountValue: '548',
+      },
+    ],
+  },
+];
+
+// Options with no `hierarchies` render as a flat list — flatness is a property of the data.
+const flatOptions: FilterOptionData[] = [
+  { id: 'white', optionValue: 'white', displayValue: 'White', displayCountValue: '1572' },
+  { id: 'black', optionValue: 'black', displayValue: 'Black', displayCountValue: '685' },
+  { id: 'red', optionValue: 'red', displayValue: 'Red', displayCountValue: '646' },
+  {
+    id: 'blue',
+    optionValue: 'blue',
+    displayValue: 'Blue',
+    displayCountValue: '394',
+    isChecked: true,
+  },
+];
+
+export const Default: Story = {
+  args: {
+    options: hierarchicalOptions,
+  },
+};
+
+export const Flat: Story = {
+  args: {
+    options: flatOptions,
+  },
+};
+
+export const DeepHierarchy: Story = {
+  args: {
+    options: hierarchicalOptions,
+  },
+  parameters: {
+    controls: { disable: true },
+  },
+};
+
+// `componentOverrides` supports three levels of customization, each demonstrated below:
+//   1. The whole list  — `reactNode` replaces the entire `<ul>`.
+//   2. Every option    — `filterOption` as an object overrides every row at every depth.
+//   3. A single option — `filterOption` as a function overrides only the rows it opts into.
+
+// --- 1. Override the whole list -------------------------------------------------------
+// A list-level `reactNode` replaces the default `<ul>` wholesale. The render-prop form
+// receives the list's props (`options`, `onChange`, …) so you can render your own layout
+// while still driving it from the same data.
+const listOverride: FilterOptionsListOverrides = {
+  reactNode: (props) => (
+    <div style={{ border: '2px dashed #6c5ce7', borderRadius: 8, padding: 12 }}>
+      <p style={{ margin: '0 0 8px', fontWeight: 600 }}>Custom list wrapper</p>
+      <ul style={{ listStyle: 'none', margin: 0, padding: 0, display: 'grid', gap: 4 }}>
+        {props?.options?.map((option) => (
+          <li
+            key={option.id}
+            style={{ padding: '4px 8px', background: '#f4f2ff', borderRadius: 4 }}>
+            {option.displayValue}
+          </li>
+        ))}
+      </ul>
+    </div>
+  ),
+};
+
+export const ListOverrideExample: Story = {
+  args: {
+    options: flatOptions,
+    componentOverrides: listOverride,
+  },
+  name: 'Override the whole list',
+  // '!autodocs' removes this story from being rendered as part of the <Stories /> component in the auto-generated docs.
+  // '!dev' prevents a story from being listed in the sidebar.
+  tags: ['!autodocs', '!dev'],
+};
+
+// --- 2. Override every option ---------------------------------------------------------
+// `filterOption` as an object applies to every `FilterOption` row at every depth.
+// Shown with flat options: a `reactNode` override replaces the whole `<li>`, so it
+// suits flat/leaf rows. The render-prop function form receives per-row render props.
+const allOptionsOverride: FilterOptionsListOverrides = {
+  filterOption: {
+    reactNode: (props) => (
+      <li style={{ padding: '6px 10px', background: '#f0f0f0', borderRadius: 4 }}>
+        {props?.displayValue} (custom)
+      </li>
+    ),
+  },
+};
+
+export const AllOptionsOverrideExample: Story = {
+  args: {
+    options: flatOptions,
+    componentOverrides: allOptionsOverride,
+  },
+  name: 'Override every option',
+  tags: ['!autodocs', '!dev'],
+};
+
+// --- 3. Override a single option ------------------------------------------------------
+// `filterOption` as a function is called per option; return overrides only for the rows
+// you want to customize and `undefined` for the rest. The matched row here is a parent,
+// and re-emitting `props.children` keeps its nested list, so the override customizes one
+// row without collapsing the hierarchy beneath it.
+const singleOptionOverride: FilterOptionsListOverrides = {
+  filterOption: (option) =>
+    option.id === 'apparel-mens'
+      ? {
+        reactNode: (props) => (
+          <li style={{ display: 'flex', flexDirection: 'column' }}>
+            <strong style={{ padding: '6px 10px', background: '#fff3cd', borderRadius: 4 }}>
+              {props?.displayValue} (highlighted)
+            </strong>
+            {props?.children}
+          </li>
+        ),
+      }
+      : undefined,
+};
+
+export const SingleOptionOverrideExample: Story = {
+  args: {
+    options: hierarchicalOptions,
+    componentOverrides: singleOptionOverride,
+  },
+  name: 'Override a specific option (keeps nesting)',
+  tags: ['!autodocs', '!dev'],
+};

From 02a80b172e70fa738df31e1098952bf971ab9bac Mon Sep 17 00:00:00 2001
From: Sherzod Baxodirov <sherzod.baxodirov@constructor.io>
Date: Mon, 10 Aug 2026 21:59:05 +0500
Subject: [PATCH 2/4] chore: linting

---
 .../FilterOptionsList.stories.tsx             | 20 +++++++++----------
 1 file changed, 10 insertions(+), 10 deletions(-)

diff --git a/src/stories/components/FilterOptionsList/FilterOptionsList.stories.tsx b/src/stories/components/FilterOptionsList/FilterOptionsList.stories.tsx
index e670f9a..29b8a98 100644
--- a/src/stories/components/FilterOptionsList/FilterOptionsList.stories.tsx
+++ b/src/stories/components/FilterOptionsList/FilterOptionsList.stories.tsx
@@ -12,7 +12,7 @@ const meta = {
   },
   tags: ['autodocs'],
   args: {
-    onChange: () => { },
+    onChange: () => {},
   },
   argTypes: {
     checkboxPosition: {
@@ -203,15 +203,15 @@ const singleOptionOverride: FilterOptionsListOverrides = {
   filterOption: (option) =>
     option.id === 'apparel-mens'
       ? {
-        reactNode: (props) => (
-          <li style={{ display: 'flex', flexDirection: 'column' }}>
-            <strong style={{ padding: '6px 10px', background: '#fff3cd', borderRadius: 4 }}>
-              {props?.displayValue} (highlighted)
-            </strong>
-            {props?.children}
-          </li>
-        ),
-      }
+          reactNode: (props) => (
+            <li style={{ display: 'flex', flexDirection: 'column' }}>
+              <strong style={{ padding: '6px 10px', background: '#fff3cd', borderRadius: 4 }}>
+                {props?.displayValue} (highlighted)
+              </strong>
+              {props?.children}
+            </li>
+          ),
+        }
       : undefined,
 };
 

From 2cc972e3fb3ed1af9dc39baa4540db8059161e91 Mon Sep 17 00:00:00 2001
From: Sherzod Baxodirov <sherzod.baxodirov@constructor.io>
Date: Wed, 19 Aug 2026 20:11:00 +0500
Subject: [PATCH 3/4] feat: add collapsible branches and visual rows to
 FilterOptionsList

---
 .../FilterOption/FilterOption.test.tsx        |  14 +
 .../FilterOptionVisual.test.tsx               |  55 ++
 .../FilterOptionsList.test.tsx                | 723 ++++++++++++++++--
 src/components/filter-option--visual.tsx      |  11 +-
 src/components/filter-option.tsx              |   7 +-
 src/components/filter-options-list.tsx        | 369 +++++++--
 src/index.ts                                  |   1 +
 .../FilterOptionsList.stories.tsx             | 171 ++++-
 8 files changed, 1240 insertions(+), 111 deletions(-)

diff --git a/spec/components/FilterOption/FilterOption.test.tsx b/spec/components/FilterOption/FilterOption.test.tsx
index 4ab16ad..da07dbc 100644
--- a/spec/components/FilterOption/FilterOption.test.tsx
+++ b/spec/components/FilterOption/FilterOption.test.tsx
@@ -261,6 +261,20 @@ describe('FilterOption component', () => {
       const listItem = screen.getByRole('listitem');
       expect(listItem.classList.contains('cio:text-base')).toBeTruthy();
     });
+
+    test('label takes the leftover space rather than sizing to its text', () => {
+      const { container } = render(
+        <FilterOption id='test-1' optionValue='red' displayValue='Red' onChange={() => {}}>
+          <button type='button'>beside the label</button>
+        </FilterOption>,
+      );
+      // `grow basis-0 min-w-0`: a long display value wraps inside the label instead of claiming
+      // the whole flex line and pushing a sibling (e.g. a hierarchy toggle) onto its own line.
+      const label = container.querySelector('.cio-filter-option-label');
+      expect(label?.classList.contains('cio:grow')).toBeTruthy();
+      expect(label?.classList.contains('cio:basis-0')).toBeTruthy();
+      expect(label?.classList.contains('cio:min-w-0')).toBeTruthy();
+    });
   });
 
   describe('data attributes', () => {
diff --git a/spec/components/FilterOptionVisual/FilterOptionVisual.test.tsx b/spec/components/FilterOptionVisual/FilterOptionVisual.test.tsx
index 86f8a85..518f215 100644
--- a/spec/components/FilterOptionVisual/FilterOptionVisual.test.tsx
+++ b/spec/components/FilterOptionVisual/FilterOptionVisual.test.tsx
@@ -183,6 +183,61 @@ describe('FilterOptionVisual component', () => {
     });
   });
 
+  describe('children', () => {
+    test('renders children inside the row', () => {
+      render(
+        <FilterOptionVisual
+          id='test-1'
+          optionValue='red'
+          displayValue='Red'
+          visualType='color'
+          visualValue='#FF0000'
+          onChange={() => {}}>
+          <span data-testid='nested'>Nested</span>
+        </FilterOptionVisual>,
+      );
+      const listItem = screen.getByRole('listitem');
+      expect(listItem).toContainElement(screen.getByTestId('nested'));
+    });
+
+    test('renders children outside the label, after it', () => {
+      render(
+        <FilterOptionVisual
+          id='test-1'
+          optionValue='red'
+          displayValue='Red'
+          visualType='color'
+          visualValue='#FF0000'
+          onChange={() => {}}>
+          <button type='button' data-testid='nested-control'>
+            Toggle
+          </button>
+        </FilterOptionVisual>,
+      );
+      const child = screen.getByTestId('nested-control');
+      // Interactive children must stay out of the <label>: a nested control is invalid markup
+      // there and its clicks would also fire the row's checkbox.
+      expect(child.closest('label')).toBeNull();
+      expect(child.previousElementSibling).toBe(document.querySelector('.cio-filter-option-label'));
+    });
+
+    test('renders no extra nodes when children are omitted', () => {
+      render(
+        <FilterOptionVisual
+          id='test-1'
+          optionValue='red'
+          displayValue='Red'
+          visualType='color'
+          visualValue='#FF0000'
+          onChange={() => {}}
+        />,
+      );
+      const listItem = screen.getByRole('listitem');
+      expect(listItem.children).toHaveLength(1);
+      expect(listItem.children[0].classList.contains('cio-filter-option-label')).toBeTruthy();
+    });
+  });
+
   describe('checkbox default position', () => {
     test('checkbox defaults to right position', () => {
       render(
diff --git a/spec/components/FilterOptionsList/FilterOptionsList.test.tsx b/spec/components/FilterOptionsList/FilterOptionsList.test.tsx
index 17c5cab..51c5639 100644
--- a/spec/components/FilterOptionsList/FilterOptionsList.test.tsx
+++ b/spec/components/FilterOptionsList/FilterOptionsList.test.tsx
@@ -1,7 +1,10 @@
 import React from 'react';
 import { render, screen, cleanup, fireEvent } from '@testing-library/react';
 import { describe, test, expect, afterEach, vi } from 'vitest';
-import FilterOptionsList, { type FilterOptionData } from '@/components/filter-options-list';
+import FilterOptionsList, {
+  type FilterOptionData,
+  type FilterOptionVisualData,
+} from '@/components/filter-options-list';
 
 // A 3-level fixture reused across tests.
 const nestedOptions: FilterOptionData[] = [
@@ -10,13 +13,13 @@ const nestedOptions: FilterOptionData[] = [
     optionValue: 'level-0',
     displayValue: 'Level 0',
     displayCountValue: '100',
-    hierarchies: [
+    options: [
       {
         id: 'l1',
         optionValue: 'level-1',
         displayValue: 'Level 1',
         isChecked: true,
-        hierarchies: [
+        options: [
           {
             id: 'l2',
             optionValue: 'level-2',
@@ -41,7 +44,7 @@ describe('FilterOptionsList component', () => {
 
   describe('flat data', () => {
     test('renders all options as sibling rows', () => {
-      render(<FilterOptionsList options={flatOptions} onChange={() => { }} />);
+      render(<FilterOptionsList options={flatOptions} onChange={() => {}} />);
       expect(screen.getByText('Alpha')).toBeInTheDocument();
       expect(screen.getByText('Bravo')).toBeInTheDocument();
       expect(screen.getByText('Charlie')).toBeInTheDocument();
@@ -49,7 +52,7 @@ describe('FilterOptionsList component', () => {
     });
 
     test('renders a single top-level list without indentation', () => {
-      const { container } = render(<FilterOptionsList options={flatOptions} onChange={() => { }} />);
+      const { container } = render(<FilterOptionsList options={flatOptions} onChange={() => {}} />);
       const lists = container.querySelectorAll('[data-slot="filter-options-list"]');
       expect(lists).toHaveLength(1);
       expect(lists[0].classList.contains('cio:pl-4')).toBeFalsy();
@@ -57,8 +60,8 @@ describe('FilterOptionsList component', () => {
   });
 
   describe('hierarchical rendering', () => {
-    test('recurses into hierarchies at every depth', () => {
-      render(<FilterOptionsList options={nestedOptions} onChange={() => { }} />);
+    test('recurses into nested options at every depth', () => {
+      render(<FilterOptionsList options={nestedOptions} onChange={() => {}} />);
       // A leaf several levels deep is present.
       expect(screen.getByText('Level 0')).toBeInTheDocument();
       expect(screen.getByText('Level 1')).toBeInTheDocument();
@@ -67,46 +70,101 @@ describe('FilterOptionsList component', () => {
 
     test('renders a nested list per level with a data-slot', () => {
       const { container } = render(
-        <FilterOptionsList options={nestedOptions} onChange={() => { }} />,
+        <FilterOptionsList options={nestedOptions} onChange={() => {}} />,
       );
       // Root + Level 0's children + Level 1's children = 3 lists.
       expect(container.querySelectorAll('[data-slot="filter-options-list"]')).toHaveLength(3);
     });
 
-    test('indents nested lists but not the root', () => {
+    test('indents rows in nested lists but not root rows', () => {
+      render(<FilterOptionsList options={nestedOptions} onChange={() => {}} />);
+      // Indentation sits on the nested rows rather than on the nested list itself, so the list
+      // can stay width-neutral (next test). It still compounds with depth via DOM nesting.
+      const isIndented = (label: string) =>
+        screen.getByText(label).closest('li')?.classList.contains('cio:pl-4');
+      expect(isIndented('Level 0')).toBeFalsy();
+      expect(isIndented('Level 1')).toBeTruthy();
+      expect(isIndented('Level 2')).toBeTruthy();
+    });
+
+    test('nested lists cannot widen the list when a branch expands', () => {
       const { container } = render(
-        <FilterOptionsList options={nestedOptions} onChange={() => { }} />,
+        <FilterOptionsList options={nestedOptions} onChange={() => {}} />,
       );
       const lists = Array.from(container.querySelectorAll('[data-slot="filter-options-list"]'));
-      const indented = lists.filter((el) => el.classList.contains('cio:pl-4'));
-      // Every list except the root is indented.
-      expect(indented).toHaveLength(lists.length - 1);
-      expect(lists[0].classList.contains('cio:pl-4')).toBeFalsy();
+      // `w-0` keeps a nested list out of the list's intrinsic width - expanding a branch cannot
+      // widen a content-sized panel - and `min-w-full` sizes it back to its row's full width.
+      const widthNeutral = lists.filter(
+        (el) => el.classList.contains('cio:w-0') && el.classList.contains('cio:min-w-full'),
+      );
+      expect(widthNeutral).toHaveLength(lists.length - 1);
+      expect(lists[0].classList.contains('cio:w-0')).toBeFalsy();
     });
 
-    test('parent rows with children get cio:flex-col to stack the nested list below', () => {
-      render(<FilterOptionsList options={nestedOptions} onChange={() => { }} />);
+    test('parent rows wrap so the nested list takes the line below the row', () => {
+      render(<FilterOptionsList options={nestedOptions} onChange={() => {}} />);
       const parentRow = screen.getByText('Level 0').closest('li');
-      expect(parentRow?.classList.contains('cio:flex-col')).toBeTruthy();
+      expect(parentRow?.classList.contains('cio:flex-wrap')).toBeTruthy();
       const leafRow = screen.getByText('Level 2').closest('li');
-      expect(leafRow?.classList.contains('cio:flex-col')).toBeFalsy();
+      expect(leafRow?.classList.contains('cio:flex-wrap')).toBeFalsy();
+    });
+
+    test('nested lists are full-width flex items so they wrap onto their own line', () => {
+      const { container } = render(
+        <FilterOptionsList options={nestedOptions} onChange={() => {}} />,
+      );
+      const lists = Array.from(container.querySelectorAll('[data-slot="filter-options-list"]'));
+      const fullWidth = lists.filter((el) => el.classList.contains('cio:basis-full'));
+      expect(fullWidth).toHaveLength(lists.length - 1);
+      expect(lists[0].classList.contains('cio:basis-full')).toBeFalsy();
     });
   });
 
   describe('selection at each depth', () => {
     test.each([
-      ['Level 0', 'level-0'],
-      ['Level 1', 'level-1'],
-      ['Level 2', 'level-2'],
-    ])('calls onChange with the option value when %s is clicked', (label, value) => {
+      ['Level 0', 'level-0', 'l0'],
+      ['Level 1', 'level-1', 'l1'],
+      ['Level 2', 'level-2', 'l2'],
+    ])('calls onChange with the value and the option when %s is clicked', (label, value, id) => {
       const handleChange = vi.fn();
       render(<FilterOptionsList options={nestedOptions} onChange={handleChange} />);
       fireEvent.click(screen.getByText(label));
-      expect(handleChange).toHaveBeenCalledWith(value);
+      expect(handleChange).toHaveBeenCalledWith(value, expect.objectContaining({ id }));
+    });
+
+    test('passes the option object the consumer supplied, not a copy', () => {
+      const handleChange = vi.fn();
+      render(<FilterOptionsList options={nestedOptions} onChange={handleChange} />);
+      fireEvent.click(screen.getByText('Level 1'));
+      // Identity is preserved, so consumers can compare with `===` and reach the option's own
+      // fields - including its nested `options`.
+      expect(handleChange.mock.calls[0][1]).toBe(nestedOptions[0].options?.[0]);
+    });
+
+    test('distinguishes options that share an optionValue across branches', () => {
+      const handleChange = vi.fn();
+      const options: FilterOptionData[] = [
+        {
+          id: 'black',
+          optionValue: 'black',
+          displayValue: 'Black',
+          options: [{ id: 'black-blue', optionValue: 'blue', displayValue: 'Blue under Black' }],
+        },
+        { id: 'blue', optionValue: 'blue', displayValue: 'Blue' },
+      ];
+      render(<FilterOptionsList options={options} onChange={handleChange} />);
+      fireEvent.click(screen.getByText('Blue under Black'));
+      fireEvent.click(screen.getByText('Blue'));
+      // Both report the value 'blue'; only the second argument tells them apart.
+      expect(handleChange.mock.calls.map(([value]) => value)).toEqual(['blue', 'blue']);
+      expect(handleChange.mock.calls.map(([, option]) => option.id)).toEqual([
+        'black-blue',
+        'blue',
+      ]);
     });
 
     test('reflects isChecked state per depth', () => {
-      render(<FilterOptionsList options={nestedOptions} onChange={() => { }} />);
+      render(<FilterOptionsList options={nestedOptions} onChange={() => {}} />);
       // Level 1 is the only pre-checked node.
       expect(screen.getByText('Level 0').closest('li')?.querySelector('input')).not.toBeChecked();
       expect(screen.getByText('Level 1').closest('li')?.querySelector('input')).toBeChecked();
@@ -114,12 +172,576 @@ describe('FilterOptionsList component', () => {
     });
   });
 
+  describe('collapsible branches', () => {
+    // Scoped by data-slot rather than by role, so these counts keep meaning the number of
+    // hierarchy toggles if a row ever grows a button of its own.
+    const toggles = () =>
+      Array.from(document.querySelectorAll('[data-slot="filter-option-hierarchy-toggle"]'));
+    const spacers = () =>
+      Array.from(document.querySelectorAll('[data-slot="filter-option-hierarchy-toggle-spacer"]'));
+
+    test('only rows that have nested options get a toggle', () => {
+      render(<FilterOptionsList options={nestedOptions} onChange={() => {}} />);
+      // Level 0 and Level 1 are parents; Level 2 is a leaf.
+      expect(toggles()).toHaveLength(2);
+      expect(screen.getByText('Level 2').closest('li')?.querySelector('button')).toBeNull();
+    });
+
+    test('a flat list renders no toggles', () => {
+      render(<FilterOptionsList options={flatOptions} onChange={() => {}} />);
+      expect(toggles()).toHaveLength(0);
+    });
+
+    test('branches start expanded, with aria-expanded reflecting it', () => {
+      render(<FilterOptionsList options={nestedOptions} onChange={() => {}} />);
+      expect(screen.getByText('Level 2')).toBeInTheDocument();
+      toggles().forEach((toggle) => expect(toggle).toHaveAttribute('aria-expanded', 'true'));
+    });
+
+    test('clicking a toggle collapses the branch, and clicking again restores it', () => {
+      render(<FilterOptionsList options={nestedOptions} onChange={() => {}} />);
+      const toggle = screen.getByRole('button', { name: 'Collapse Level 0' });
+      fireEvent.click(toggle);
+      // The whole subtree below Level 0 is gone.
+      expect(screen.queryByText('Level 1')).not.toBeInTheDocument();
+      expect(screen.queryByText('Level 2')).not.toBeInTheDocument();
+      expect(screen.getByText('Level 0')).toBeInTheDocument();
+      expect(screen.getByRole('button', { name: 'Expand Level 0' })).toHaveAttribute(
+        'aria-expanded',
+        'false',
+      );
+
+      fireEvent.click(screen.getByRole('button', { name: 'Expand Level 0' }));
+      expect(screen.getByText('Level 1')).toBeInTheDocument();
+      expect(screen.getByText('Level 2')).toBeInTheDocument();
+    });
+
+    test('collapsing one branch leaves its siblings expanded', () => {
+      const options: FilterOptionData[] = [
+        {
+          id: 'a',
+          optionValue: 'a',
+          displayValue: 'Alpha',
+          options: [{ id: 'a1', optionValue: 'a1', displayValue: 'Alpha Child' }],
+        },
+        {
+          id: 'b',
+          optionValue: 'b',
+          displayValue: 'Bravo',
+          options: [{ id: 'b1', optionValue: 'b1', displayValue: 'Bravo Child' }],
+        },
+      ];
+      render(<FilterOptionsList options={options} onChange={() => {}} />);
+      fireEvent.click(screen.getByRole('button', { name: 'Collapse Alpha' }));
+      expect(screen.queryByText('Alpha Child')).not.toBeInTheDocument();
+      expect(screen.getByText('Bravo Child')).toBeInTheDocument();
+    });
+
+    test('clicking a toggle does not select the option', () => {
+      const handleChange = vi.fn();
+      render(<FilterOptionsList options={nestedOptions} onChange={handleChange} />);
+      fireEvent.click(screen.getByRole('button', { name: 'Collapse Level 0' }));
+      expect(handleChange).not.toHaveBeenCalled();
+    });
+
+    test('the toggle sits beside the label, never inside it', () => {
+      render(<FilterOptionsList options={nestedOptions} onChange={() => {}} />);
+      const row = screen.getByText('Level 0').closest('li');
+      const toggle = row?.querySelector('[data-slot="filter-option-hierarchy-toggle"]');
+      // A <button> inside a <label> is invalid and would double-fire onto the checkbox.
+      expect(toggle?.parentElement).toBe(row);
+      expect(row?.querySelector('label')?.querySelector('button')).toBeNull();
+    });
+
+    test('aria-controls points at the nested list while it is mounted', () => {
+      render(<FilterOptionsList options={nestedOptions} onChange={() => {}} />);
+      const toggle = screen.getByRole('button', { name: 'Collapse Level 0' });
+      const controls = toggle.getAttribute('aria-controls');
+      // Derived from the row's own id, so it stays predictable for consumers styling or
+      // querying the nested list.
+      expect(controls).toBe('l0-hierarchy');
+      expect(document.getElementById(controls as string)).toHaveAttribute(
+        'data-slot',
+        'filter-options-list',
+      );
+      // Collapsing unmounts the list, so the reference is dropped rather than left dangling.
+      fireEvent.click(toggle);
+      expect(
+        screen.getByRole('button', { name: 'Expand Level 0' }).getAttribute('aria-controls'),
+      ).toBeNull();
+    });
+
+    test('branches with no toggle get no generated id at all', () => {
+      const { container } = render(
+        <FilterOptionsList options={nestedOptions} collapsible={false} onChange={() => {}} />,
+      );
+      container.querySelectorAll('[data-slot="filter-options-list"]').forEach((list) => {
+        expect(list.id).toBe('');
+      });
+    });
+
+    test('option ids that collide with Object.prototype keys still respect their default', () => {
+      // `toggledIds['constructor']` resolves through the prototype chain, so a naive
+      // `!== undefined` check reads these rows as "already toggled by the user".
+      const options: FilterOptionData[] = ['constructor', 'toString', 'hasOwnProperty'].map(
+        (id) => ({
+          id,
+          optionValue: id,
+          displayValue: id,
+          defaultCollapsed: true,
+          options: [{ id: `${id}-1`, optionValue: `${id}-1`, displayValue: `${id} child` }],
+        }),
+      );
+      render(<FilterOptionsList options={options} onChange={() => {}} />);
+      options.forEach((option) => {
+        expect(screen.queryByText(`${option.id} child`)).not.toBeInTheDocument();
+        expect(screen.getByRole('button', { name: `Expand ${option.id}` })).toHaveAttribute(
+          'aria-expanded',
+          'false',
+        );
+      });
+    });
+
+    test('option ids that collide with Object.prototype keys are still toggleable', () => {
+      const options: FilterOptionData[] = [
+        {
+          id: 'constructor',
+          optionValue: 'constructor',
+          displayValue: 'Constructor',
+          options: [{ id: 'brand-1', optionValue: 'brand-1', displayValue: 'Brand Child' }],
+        },
+      ];
+      render(<FilterOptionsList options={options} onChange={() => {}} />);
+      fireEvent.click(screen.getByRole('button', { name: 'Collapse Constructor' }));
+      expect(screen.queryByText('Brand Child')).not.toBeInTheDocument();
+      fireEvent.click(screen.getByRole('button', { name: 'Expand Constructor' }));
+      expect(screen.getByText('Brand Child')).toBeInTheDocument();
+    });
+
+    test('collapsible={false} renders branches with no toggles', () => {
+      const { container } = render(
+        <FilterOptionsList options={nestedOptions} collapsible={false} onChange={() => {}} />,
+      );
+      expect(toggles()).toHaveLength(0);
+      expect(screen.getByText('Level 2')).toBeInTheDocument();
+      expect(container.querySelectorAll('[data-slot="filter-options-list"]')).toHaveLength(3);
+    });
+
+    test('defaultCollapsed starts every branch closed', () => {
+      const options: FilterOptionData[] = [
+        {
+          id: 'a',
+          optionValue: 'a',
+          displayValue: 'Alpha',
+          options: [{ id: 'a1', optionValue: 'a1', displayValue: 'Alpha Child' }],
+        },
+      ];
+      render(<FilterOptionsList options={options} defaultCollapsed onChange={() => {}} />);
+      expect(screen.queryByText('Alpha Child')).not.toBeInTheDocument();
+      expect(screen.getByRole('button', { name: 'Expand Alpha' })).toHaveAttribute(
+        'aria-expanded',
+        'false',
+      );
+    });
+
+    test('auto-expands the path to a checked option even when collapsed by default', () => {
+      render(<FilterOptionsList options={nestedOptions} defaultCollapsed onChange={() => {}} />);
+      // Level 1 is checked, so its ancestor opens to reveal it...
+      expect(screen.getByText('Level 1')).toBeInTheDocument();
+      // ...but Level 1's own branch has nothing checked, so it stays closed.
+      expect(screen.queryByText('Level 2')).not.toBeInTheDocument();
+    });
+
+    test('row-level collapsible overrides the list', () => {
+      const options: FilterOptionData[] = [
+        {
+          id: 'fixed',
+          optionValue: 'fixed',
+          displayValue: 'Fixed',
+          collapsible: false,
+          options: [{ id: 'fixed-1', optionValue: 'fixed-1', displayValue: 'Fixed Child' }],
+        },
+        {
+          id: 'toggleable',
+          optionValue: 'toggleable',
+          displayValue: 'Toggleable',
+          options: [{ id: 'tog-1', optionValue: 'tog-1', displayValue: 'Toggleable Child' }],
+        },
+      ];
+      render(<FilterOptionsList options={options} onChange={() => {}} />);
+      expect(toggles()).toHaveLength(1);
+      expect(screen.getByRole('button', { name: 'Collapse Toggleable' })).toBeInTheDocument();
+      // The non-collapsible branch is always shown.
+      expect(screen.getByText('Fixed Child')).toBeInTheDocument();
+    });
+
+    test('row-level collapsible={true} overrides a list that opted out', () => {
+      const options: FilterOptionData[] = [
+        {
+          id: 'toggleable',
+          optionValue: 'toggleable',
+          displayValue: 'Toggleable',
+          collapsible: true,
+          options: [{ id: 'tog-1', optionValue: 'tog-1', displayValue: 'Toggleable Child' }],
+        },
+        {
+          id: 'fixed',
+          optionValue: 'fixed',
+          displayValue: 'Fixed',
+          options: [{ id: 'fixed-1', optionValue: 'fixed-1', displayValue: 'Fixed Child' }],
+        },
+      ];
+      render(<FilterOptionsList options={options} collapsible={false} onChange={() => {}} />);
+      // Only the row that opted back in gets a toggle, and it still collapses.
+      expect(toggles()).toHaveLength(1);
+      fireEvent.click(screen.getByRole('button', { name: 'Collapse Toggleable' }));
+      expect(screen.queryByText('Toggleable Child')).not.toBeInTheDocument();
+      expect(screen.getByText('Fixed Child')).toBeInTheDocument();
+    });
+
+    test('row-level defaultCollapsed overrides the list default', () => {
+      const options: FilterOptionData[] = [
+        {
+          id: 'closed',
+          optionValue: 'closed',
+          displayValue: 'Closed',
+          defaultCollapsed: true,
+          options: [{ id: 'closed-1', optionValue: 'closed-1', displayValue: 'Closed Child' }],
+        },
+        {
+          id: 'open',
+          optionValue: 'open',
+          displayValue: 'Open',
+          options: [{ id: 'open-1', optionValue: 'open-1', displayValue: 'Open Child' }],
+        },
+      ];
+      render(<FilterOptionsList options={options} onChange={() => {}} />);
+      expect(screen.queryByText('Closed Child')).not.toBeInTheDocument();
+      expect(screen.getByText('Open Child')).toBeInTheDocument();
+    });
+
+    test('row-level defaultCollapsed={false} overrides a collapsed-by-default list', () => {
+      const options: FilterOptionData[] = [
+        {
+          id: 'open',
+          optionValue: 'open',
+          displayValue: 'Open',
+          defaultCollapsed: false,
+          options: [{ id: 'open-1', optionValue: 'open-1', displayValue: 'Open Child' }],
+        },
+        {
+          id: 'follows',
+          optionValue: 'follows',
+          displayValue: 'Follows',
+          options: [{ id: 'follows-1', optionValue: 'follows-1', displayValue: 'Follows Child' }],
+        },
+      ];
+      render(<FilterOptionsList options={options} defaultCollapsed onChange={() => {}} />);
+      // An explicit `false` is a value, not an absent prop, so it must beat the list default.
+      expect(screen.getByText('Open Child')).toBeInTheDocument();
+      expect(screen.queryByText('Follows Child')).not.toBeInTheDocument();
+    });
+
+    test('row-level defaultCollapsed also overrides the auto-expand rule', () => {
+      const options: FilterOptionData[] = [
+        {
+          id: 'closed',
+          optionValue: 'closed',
+          displayValue: 'Closed',
+          defaultCollapsed: true,
+          options: [
+            {
+              id: 'closed-1',
+              optionValue: 'closed-1',
+              displayValue: 'Closed Child',
+              isChecked: true,
+            },
+          ],
+        },
+      ];
+      render(<FilterOptionsList options={options} defaultCollapsed onChange={() => {}} />);
+      // An explicit value in the data wins over the derived "never hide a selection" rule.
+      expect(screen.queryByText('Closed Child')).not.toBeInTheDocument();
+    });
+
+    test('a row-level default still yields to a user toggle', () => {
+      const options: FilterOptionData[] = [
+        {
+          id: 'closed',
+          optionValue: 'closed',
+          displayValue: 'Closed',
+          defaultCollapsed: true,
+          options: [{ id: 'closed-1', optionValue: 'closed-1', displayValue: 'Closed Child' }],
+        },
+      ];
+      render(<FilterOptionsList options={options} onChange={() => {}} />);
+      fireEvent.click(screen.getByRole('button', { name: 'Expand Closed' }));
+      expect(screen.getByText('Closed Child')).toBeInTheDocument();
+    });
+
+    describe('toggle alignment spacer', () => {
+      // A level that shows any toggle gives every other row on that level an equal-width
+      // stand-in, so counts stay in one column instead of stepping left row to row.
+      const mixedLevel: FilterOptionData[] = [
+        {
+          id: 'parent',
+          optionValue: 'parent',
+          displayValue: 'Parent',
+          options: [{ id: 'child', optionValue: 'child', displayValue: 'Child' }],
+        },
+        { id: 'leaf', optionValue: 'leaf', displayValue: 'Leaf' },
+      ];
+
+      test('leaf rows on a level that has a toggle get a spacer instead', () => {
+        render(<FilterOptionsList options={mixedLevel} onChange={() => {}} />);
+        const leafRow = screen.getByText('Leaf').closest('li');
+        expect(
+          leafRow?.querySelector('[data-slot="filter-option-hierarchy-toggle-spacer"]'),
+        ).toBeInTheDocument();
+        // The row that owns the toggle needs no stand-in for it.
+        const parentRow = screen.getByText('Parent').closest('li');
+        expect(
+          parentRow?.querySelector('[data-slot="filter-option-hierarchy-toggle-spacer"]'),
+        ).toBeNull();
+        expect(spacers()).toHaveLength(1);
+      });
+
+      test('a level with no toggles gets no spacers', () => {
+        render(<FilterOptionsList options={mixedLevel} onChange={() => {}} />);
+        // 'Child' is the only row on the nested level, and nothing there has a toggle.
+        const childRow = screen.getByText('Child').closest('li');
+        expect(
+          childRow?.querySelector('[data-slot="filter-option-hierarchy-toggle-spacer"]'),
+        ).toBeNull();
+      });
+
+      test('a flat list renders no spacers', () => {
+        render(<FilterOptionsList options={flatOptions} onChange={() => {}} />);
+        expect(spacers()).toHaveLength(0);
+      });
+
+      test('collapsible={false} renders no spacers either', () => {
+        render(<FilterOptionsList options={mixedLevel} collapsible={false} onChange={() => {}} />);
+        expect(toggles()).toHaveLength(0);
+        expect(spacers()).toHaveLength(0);
+      });
+
+      test('a parent row that opted out of collapsing gets a spacer', () => {
+        const options: FilterOptionData[] = [
+          ...mixedLevel,
+          {
+            id: 'pinned',
+            optionValue: 'pinned',
+            displayValue: 'Pinned',
+            collapsible: false,
+            options: [{ id: 'pinned-1', optionValue: 'pinned-1', displayValue: 'Pinned Child' }],
+          },
+        ];
+        render(<FilterOptionsList options={options} onChange={() => {}} />);
+        const pinnedRow = screen.getByText('Pinned').closest('li');
+        expect(
+          pinnedRow?.querySelector('[data-slot="filter-option-hierarchy-toggle-spacer"]'),
+        ).toBeInTheDocument();
+      });
+
+      test('the spacer matches the footprint of the toggle it stands in for', () => {
+        render(<FilterOptionsList options={mixedLevel} onChange={() => {}} />);
+        const footprint = ['cio:w-6', 'cio:ml-1', 'cio:shrink-0'];
+        footprint.forEach((className) => {
+          expect(toggles()[0].classList.contains(className)).toBeTruthy();
+          expect(spacers()[0].classList.contains(className)).toBeTruthy();
+        });
+      });
+
+      test('the spacer is hidden from assistive technology', () => {
+        render(<FilterOptionsList options={mixedLevel} onChange={() => {}} />);
+        expect(spacers()[0]).toHaveAttribute('aria-hidden', 'true');
+      });
+    });
+
+    test('collapsing a parent preserves the toggles the user made inside it', () => {
+      render(<FilterOptionsList options={nestedOptions} onChange={() => {}} />);
+      // Close the inner branch, then close and reopen its parent.
+      fireEvent.click(screen.getByRole('button', { name: 'Collapse Level 1' }));
+      fireEvent.click(screen.getByRole('button', { name: 'Collapse Level 0' }));
+      fireEvent.click(screen.getByRole('button', { name: 'Expand Level 0' }));
+      // Level 1 comes back the way the user left it rather than reset to the default.
+      expect(screen.getByText('Level 1')).toBeInTheDocument();
+      expect(screen.queryByText('Level 2')).not.toBeInTheDocument();
+    });
+
+    test('visual rows get a toggle too', () => {
+      const options: FilterOptionData[] = [
+        {
+          id: 'v-blue',
+          optionValue: 'blue',
+          displayValue: 'Blue',
+          visual: { type: 'color', value: '#0000FF' },
+          options: [
+            {
+              id: 'v-navy',
+              optionValue: 'navy',
+              displayValue: 'Navy',
+              visual: { type: 'color', value: '#000080' },
+            },
+          ],
+        },
+      ];
+      render(<FilterOptionsList options={options} onChange={() => {}} />);
+      fireEvent.click(screen.getByRole('button', { name: 'Collapse Blue' }));
+      expect(screen.queryByText('Navy')).not.toBeInTheDocument();
+      expect(document.querySelectorAll('.cio-filter-visual-swatch')).toHaveLength(1);
+    });
+  });
+
+  describe('visual options', () => {
+    const visualOptions: FilterOptionData[] = [
+      {
+        id: 'v-red',
+        optionValue: 'red',
+        displayValue: 'Red',
+        visual: { type: 'color', value: '#FF0000' },
+      },
+      {
+        id: 'v-floral',
+        optionValue: 'floral',
+        displayValue: 'Floral',
+        visual: { type: 'image', value: 'https://example.com/pattern.jpg' },
+      },
+    ];
+
+    test('renders a visual row for options carrying a visual', () => {
+      render(<FilterOptionsList options={visualOptions} onChange={() => {}} />);
+      const rows = screen.getAllByRole('listitem');
+      expect(rows).toHaveLength(2);
+      rows.forEach((row) => expect(row).toHaveAttribute('data-slot', 'visual-filter-option'));
+    });
+
+    test('renders a color swatch and an image swatch from the data', () => {
+      render(<FilterOptionsList options={visualOptions} onChange={() => {}} />);
+      const swatches = document.querySelectorAll('.cio-filter-visual-swatch');
+      expect(swatches).toHaveLength(2);
+      expect(swatches[0]).toHaveStyle({ backgroundColor: 'rgb(255, 0, 0)' });
+      expect(screen.getByAltText('Floral')).toHaveAttribute(
+        'src',
+        'https://example.com/pattern.jpg',
+      );
+    });
+
+    test('falls back to a plain row when only one half of the visual is present', () => {
+      // TypeScript requires both halves of `visual`, so only a JS consumer can build these -
+      // hence the casts. They must degrade to plain rows rather than render an empty swatch.
+      const partial: FilterOptionData[] = [
+        {
+          id: 'p1',
+          optionValue: 'p1',
+          displayValue: 'Type only',
+          visual: { type: 'color' } as FilterOptionVisualData,
+        },
+        {
+          id: 'p2',
+          optionValue: 'p2',
+          displayValue: 'Value only',
+          visual: { value: '#FF0000' } as FilterOptionVisualData,
+        },
+      ];
+      render(<FilterOptionsList options={partial} onChange={() => {}} />);
+      screen.getAllByRole('listitem').forEach((row) => {
+        expect(row).toHaveAttribute('data-slot', 'filter-option');
+      });
+      expect(document.querySelector('.cio-filter-visual-swatch')).toBeNull();
+    });
+
+    test('mixes visual and plain rows in the same list', () => {
+      const options: FilterOptionData[] = [
+        ...visualOptions,
+        { id: 'plain', optionValue: 'plain', displayValue: 'Plain' },
+      ];
+      render(<FilterOptionsList options={options} onChange={() => {}} />);
+      expect(screen.getByText('Plain').closest('li')).toHaveAttribute('data-slot', 'filter-option');
+      expect(screen.getByText('Red').closest('li')).toHaveAttribute(
+        'data-slot',
+        'visual-filter-option',
+      );
+    });
+
+    test('a visual row keeps its nested options', () => {
+      const options: FilterOptionData[] = [
+        {
+          id: 'v-blue',
+          optionValue: 'blue',
+          displayValue: 'Blue',
+          visual: { type: 'color', value: '#0000FF' },
+          options: [
+            {
+              id: 'v-navy',
+              optionValue: 'navy',
+              displayValue: 'Navy',
+              visual: { type: 'color', value: '#000080' },
+            },
+          ],
+        },
+      ];
+      const { container } = render(<FilterOptionsList options={options} onChange={() => {}} />);
+      expect(screen.getByText('Navy')).toBeInTheDocument();
+      expect(container.querySelectorAll('[data-slot="filter-options-list"]')).toHaveLength(2);
+      const parentRow = screen.getByText('Blue').closest('li');
+      expect(parentRow?.classList.contains('cio:flex-wrap')).toBeTruthy();
+    });
+
+    test('calls onChange with the value and the option when a visual row is clicked', () => {
+      const handleChange = vi.fn();
+      render(<FilterOptionsList options={visualOptions} onChange={handleChange} />);
+      fireEvent.click(screen.getByText('Floral'));
+      expect(handleChange).toHaveBeenCalledWith('floral', visualOptions[1]);
+    });
+
+    test('forwards checkboxPosition to visual rows, overriding their default', () => {
+      render(
+        <FilterOptionsList options={visualOptions} checkboxPosition='left' onChange={() => {}} />,
+      );
+      const label = screen.getByText('Red').closest('label');
+      const display = label?.querySelector('.cio-filter-multiple-option-display');
+      // 'left' puts the checkbox before the display block.
+      expect(display?.previousElementSibling?.classList.contains('cio-checkbox')).toBeTruthy();
+    });
+
+    test('the swatch wins over a startContent passed alongside it', () => {
+      render(
+        <FilterOptionsList
+          options={[{ ...visualOptions[0], startContent: <span>custom start</span> }]}
+          onChange={() => {}}
+        />,
+      );
+      expect(screen.queryByText('custom start')).not.toBeInTheDocument();
+      expect(document.querySelector('.cio-filter-visual-swatch')).toBeInTheDocument();
+    });
+
+    test('row-level overrides apply to visual rows too', () => {
+      render(
+        <FilterOptionsList
+          options={visualOptions}
+          onChange={() => {}}
+          componentOverrides={{
+            filterOption: (option) =>
+              option.visual?.type === 'image'
+                ? { reactNode: <li data-testid='visual-override'>Custom</li> }
+                : undefined,
+          }}
+        />,
+      );
+      expect(screen.getByTestId('visual-override')).toBeInTheDocument();
+      expect(screen.queryByText('Floral')).not.toBeInTheDocument();
+      expect(screen.getByText('Red')).toBeInTheDocument();
+    });
+  });
+
   describe('componentOverrides', () => {
     test('list-level reactNode replaces the entire list', () => {
       render(
         <FilterOptionsList
           options={flatOptions}
-          onChange={() => { }}
+          onChange={() => {}}
           componentOverrides={{
             reactNode: <ul data-testid='custom-list'>Custom list</ul>,
           }}
@@ -133,7 +755,7 @@ describe('FilterOptionsList component', () => {
       render(
         <FilterOptionsList
           options={flatOptions}
-          onChange={() => { }}
+          onChange={() => {}}
           componentOverrides={{
             filterOption: {
               reactNode: <li data-testid='custom-row'>Custom row</li>,
@@ -149,7 +771,7 @@ describe('FilterOptionsList component', () => {
       render(
         <FilterOptionsList
           options={flatOptions}
-          onChange={() => { }}
+          onChange={() => {}}
           componentOverrides={{
             filterOption: (option) =>
               option.id === 'b'
@@ -169,7 +791,7 @@ describe('FilterOptionsList component', () => {
       render(
         <FilterOptionsList
           options={nestedOptions}
-          onChange={() => { }}
+          onChange={() => {}}
           componentOverrides={{
             filterOption: (option) =>
               option.id === 'l2'
@@ -189,18 +811,18 @@ describe('FilterOptionsList component', () => {
       const { container } = render(
         <FilterOptionsList
           options={nestedOptions}
-          onChange={() => { }}
+          onChange={() => {}}
           componentOverrides={{
             filterOption: (option) =>
               option.id === 'l0'
                 ? {
-                  reactNode: (props) => (
-                    <li data-testid='parent-override'>
-                      {props.displayValue}
-                      {props.children}
-                    </li>
-                  ),
-                }
+                    reactNode: (props) => (
+                      <li data-testid='parent-override'>
+                        {props.displayValue}
+                        {props.children}
+                      </li>
+                    ),
+                  }
                 : undefined,
           }}
         />,
@@ -214,33 +836,35 @@ describe('FilterOptionsList component', () => {
     });
   });
 
-  describe('empty hierarchies guard', () => {
-    test('a node with an empty hierarchies array renders no nested list and no flex-col', () => {
+  describe('empty nested options guard', () => {
+    test('a node with an empty options array renders as a plain leaf row', () => {
       const options: FilterOptionData[] = [
-        { id: 'leaf', optionValue: 'leaf', displayValue: 'Leaf', hierarchies: [] },
+        { id: 'leaf', optionValue: 'leaf', displayValue: 'Leaf', options: [] },
       ];
-      const { container } = render(<FilterOptionsList options={options} onChange={() => { }} />);
+      const { container } = render(<FilterOptionsList options={options} onChange={() => {}} />);
       expect(container.querySelectorAll('[data-slot="filter-options-list"]')).toHaveLength(1);
       expect(
-        screen.getByText('Leaf').closest('li')?.classList.contains('cio:flex-col'),
+        screen.getByText('Leaf').closest('li')?.classList.contains('cio:flex-wrap'),
       ).toBeFalsy();
+      // No nested options means nothing to collapse, so no toggle either.
+      expect(screen.queryByRole('button')).not.toBeInTheDocument();
     });
   });
 
   describe('conventions', () => {
     test('has data-slot attribute on the root list', () => {
-      render(<FilterOptionsList options={flatOptions} onChange={() => { }} />);
+      render(<FilterOptionsList options={flatOptions} onChange={() => {}} />);
       expect(screen.getByRole('list')).toHaveAttribute('data-slot', 'filter-options-list');
     });
 
     test('has cio-filter-options-list class', () => {
-      render(<FilterOptionsList options={flatOptions} onChange={() => { }} />);
+      render(<FilterOptionsList options={flatOptions} onChange={() => {}} />);
       expect(screen.getByRole('list').classList.contains('cio-filter-options-list')).toBeTruthy();
     });
 
     test('merges custom className onto the root list', () => {
       render(
-        <FilterOptionsList options={flatOptions} className='my-custom-class' onChange={() => { }} />,
+        <FilterOptionsList options={flatOptions} className='my-custom-class' onChange={() => {}} />,
       );
       expect(screen.getByRole('list').classList.contains('my-custom-class')).toBeTruthy();
     });
@@ -251,7 +875,7 @@ describe('FilterOptionsList component', () => {
           options={flatOptions}
           data-testid='my-list'
           data-facet='color'
-          onChange={() => { }}
+          onChange={() => {}}
         />,
       );
       expect(screen.getByTestId('my-list').dataset.facet).toBe('color');
@@ -266,19 +890,22 @@ describe('FilterOptionsList component', () => {
           id: 'branch-a',
           optionValue: 'branch-a',
           displayValue: 'Branch A',
-          hierarchies: [{ id: 'a-child', optionValue: 'a-child', displayValue: 'A Child' }],
+          options: [{ id: 'a-child', optionValue: 'a-child', displayValue: 'A Child' }],
         },
         {
           id: 'branch-b',
           optionValue: 'branch-b',
           displayValue: 'Branch B',
-          hierarchies: [{ id: 'b-child', optionValue: 'b-child', displayValue: 'B Child' }],
+          options: [{ id: 'b-child', optionValue: 'b-child', displayValue: 'B Child' }],
         },
       ];
       render(<FilterOptionsList options={options} onChange={handleChange} />);
       fireEvent.click(screen.getByText('A Child'));
       expect(handleChange).toHaveBeenCalledTimes(1);
-      expect(handleChange).toHaveBeenCalledWith('a-child');
+      expect(handleChange).toHaveBeenCalledWith(
+        'a-child',
+        expect.objectContaining({ id: 'a-child' }),
+      );
     });
   });
 });
diff --git a/src/components/filter-option--visual.tsx b/src/components/filter-option--visual.tsx
index dfcc402..7cbe884 100644
--- a/src/components/filter-option--visual.tsx
+++ b/src/components/filter-option--visual.tsx
@@ -3,8 +3,7 @@ import { cn } from '@/utils';
 import Chip from '@/components/chip';
 import FilterOption, { type FilterOptionProps } from '@/components/filter-option';
 
-export interface FilterOptionVisualProps
-  extends Omit<FilterOptionProps, 'startContent' | 'children'> {
+export interface FilterOptionVisualProps extends Omit<FilterOptionProps, 'startContent'> {
   /** Type of visual - 'color' for hex colors, 'image' for image URLs */
   visualType: 'color' | 'image';
   /** The visual value - hex color code or image URL */
@@ -17,10 +16,12 @@ export default function FilterOptionVisual({
   visualType,
   visualValue,
   displayValue,
+  children,
   ...props
 }: FilterOptionVisualProps) {
   return (
     <FilterOption
+      {...props}
       checkboxPosition={checkboxPosition}
       displayValue={displayValue}
       className={cn('cio-visual-filter-option', className)}
@@ -32,8 +33,8 @@ export default function FilterOptionVisual({
           name={displayValue}
           className='cio-filter-visual-swatch cio:mr-2 cio:shrink-0'
         />
-      }
-      {...props}
-    />
+      }>
+      {children}
+    </FilterOption>
   );
 }
diff --git a/src/components/filter-option.tsx b/src/components/filter-option.tsx
index 13b7558..e8eadf7 100644
--- a/src/components/filter-option.tsx
+++ b/src/components/filter-option.tsx
@@ -4,6 +4,9 @@ import { ComponentOverrideProps, IncludeComponentOverrides } from '@/types';
 const baseClasses =
   'cio-components cio-filter-option cio-filter-multiple-option cio:flex cio:list-none cio:text-base';
 
+const labelClasses =
+  'cio-filter-option-label cio:group cio:text-sm cio:flex cio:flex-row cio:items-center cio:cursor-pointer cio:grow cio:basis-0 cio:min-w-0 cio:p-1 cio:hover:bg-neutral-100 cio:hover:rounded';
+
 export interface FilterOptionProps
   extends Omit<React.ComponentProps<'li'>, 'onChange' | 'children'>,
     IncludeComponentOverrides<FilterOptionOverrides> {
@@ -90,9 +93,7 @@ export default function FilterOption({
   return (
     <RenderPropsWrapper props={renderProps} override={componentOverrides?.reactNode}>
       <li data-slot='filter-option' className={cn(baseClasses, className)} {...props}>
-        <label
-          htmlFor={id}
-          className='cio-filter-option-label cio:group cio:text-sm cio:flex cio:flex-row cio:items-center cio:cursor-pointer cio:grow cio:p-1 cio:hover:bg-neutral-100 cio:hover:rounded'>
+        <label htmlFor={id} className={labelClasses}>
           <input
             type='checkbox'
             id={id}
diff --git a/src/components/filter-options-list.tsx b/src/components/filter-options-list.tsx
index 45ee035..02a300c 100644
--- a/src/components/filter-options-list.tsx
+++ b/src/components/filter-options-list.tsx
@@ -5,53 +5,121 @@ import FilterOption, {
   type FilterOptionProps,
   type FilterOptionOverrides,
 } from '@/components/filter-option';
+import FilterOptionVisual, {
+  type FilterOptionVisualProps,
+} from '@/components/filter-option--visual';
 
 const baseClasses =
   'cio-components cio-filter-options-list cio:list-none cio:p-0 cio:m-0 cio:flex cio:flex-col';
 
 /**
- * A single option in a {@link FilterOptionsList}. Self-similar: an option can nest
- * child options under `hierarchies`, which are rendered nested and indented. The shape
- * is intentionally data-agnostic.
+ * ClassName for hierarchy toggle. Shared with the spacer used in rows without hierarchy for visual consistency
+ */
+const toggleFootprintClasses = 'cio:w-6 cio:ml-1 cio:shrink-0';
+
+/* Makes nested lists wrap to a new flex line without contributing to the parent’s intrinsic width. */
+const nestedListClasses = 'cio:basis-full cio:w-0 cio:min-w-full';
+
+/** Indentation for a row inside a nested list. Compounds with depth via DOM nesting. */
+const nestedRowClasses = 'cio:pl-4';
+
+/**
+ * The swatch shown on a visual (`FilterOptionVisual`) row. `type` and `value` travel together
+ * because neither means anything alone - a row is a swatch row exactly when it carries a
+ * complete `visual`.
+ */
+export interface FilterOptionVisualData {
+  /** `'color'` for a hex color swatch, `'image'` for an image swatch */
+  type: FilterOptionVisualProps['visualType'];
+  /** Hex color code or image URL, matching `type` */
+  value: FilterOptionVisualProps['visualValue'];
+}
+
+/**
+ * A single option in a {@link FilterOptionsList}. An option can nest child options under
+ * `options` - the same key the list itself takes - which are rendered nested and indented.
+ *
+ * An option renders as a `FilterOptionVisual` (swatch row) when it carries a `visual`, and as a
+ * plain `FilterOption` otherwise. Visual and plain options can be mixed freely, at any depth.
  *
- * Note: `id`s must be unique across the entire tree — `FilterOption` uses `id` for its
- * `<input id>` / `<label htmlFor>` pair, so duplicate ids across branches break label
- * association.
+ * `id`s must be unique across the entire document
+ * `FilterOption` uses `id` for its `<input id>` / `<label htmlFor>` pair, and a row with nested
+ * `options` also derives `<id>-hierarchy` for the `aria-controls` target of its nested list.
+ * Duplicate ids break label association, so a page rendering several lists is responsible for
+ * namespacing them, and the `-hierarchy` suffix is reserved.
  */
 export interface FilterOptionData
   extends Pick<
     FilterOptionProps,
     'id' | 'optionValue' | 'displayValue' | 'displayCountValue' | 'isChecked' | 'startContent'
   > {
-  /** Child options — rendered nested and indented. Omit (or leave empty) for a leaf row. */
-  hierarchies?: FilterOptionData[];
+  /** Child options - rendered nested and indented. Omit (or leave empty) for a leaf row. */
+  options?: FilterOptionData[];
+  /** Swatch to render in place of the row's `startContent`, making this a visual row. */
+  visual?: FilterOptionVisualData;
+  /**
+   * Whether **this** row's nested `options` get a collapse toggle. Overrides the list's
+   * `collapsible` for this row only - e.g. to keep one short branch always open while long ones
+   * collapse. Ignored on rows without nested `options`.
+   */
+  collapsible?: boolean;
+  /**
+   * Whether **this** row's nested `options` start collapsed. Overrides both the list's
+   * `defaultCollapsed` and the auto-expand rule (see
+   * {@link FilterOptionsListProps.defaultCollapsed}). Initial state only - the component owns
+   * expansion after the first render, so changing this later has no effect on a branch the user
+   * has already toggled.
+   */
+  defaultCollapsed?: boolean;
 }
 
 export interface FilterOptionsListProps
   extends Omit<React.ComponentProps<'ul'>, 'onChange' | 'children'>,
     IncludeComponentOverrides<FilterOptionsListOverrides> {
   /**
-   * Options to render. Each option's `hierarchies` are recursed into, nesting + indenting
-   * each level; hierarchy is driven entirely by the data, so options without `hierarchies`
-   * render as a flat list.
+   * Options to render. Each option's nested `options` are recursed into, nesting + indenting
+   * each level; options without nested `options` render as a flat list.
    */
   options: FilterOptionData[];
-  /** Callback when any option's selection changes; receives the option's `optionValue` */
-  onChange: (value: string) => void;
-  /** Position of each option's checkbox. Forwarded to every `FilterOption`. */
+  /**
+   * Callback when any option's selection changes, at any depth. Receives the option's
+   * `optionValue` and the option itself - the same object from `options`, so `===` and `id`
+   * both identify it. Two options in different branches can share an `optionValue`, so use the
+   * second argument when the value alone is ambiguous.
+   */
+  onChange: (value: string, option: FilterOptionData) => void;
+  /**
+   * Position of each option's checkbox. Forwarded to every row. When omitted, each row keeps
+   * its own component default - `left` for plain options, `right` for visual (swatch) ones.
+   */
   checkboxPosition?: FilterOptionProps['checkboxPosition'];
+  /**
+   * Whether rows that have nested `options` get a toggle that collapses their nested list. This
+   * collapses branches **within** the list. Rows without nested `options` are unaffected.
+   * Per-row `collapsible` wins over this. Defaults to `true`.
+   */
+  collapsible?: boolean;
+  /**
+   * Whether every branch starts collapsed rather than expanded. Initial state only - the
+   * component owns expansion from then on. Defaults to `false`.
+   *
+   * A branch holding a checked option auto-expands even when this is `true`, so an applied
+   * filter is never hidden; per-row `defaultCollapsed` overrides both.
+   */
+  defaultCollapsed?: boolean;
 }
 
 /**
- * Row-level override for a {@link FilterOptionsList}. Either:
- * - an object applied to **every** `FilterOption` row at every depth, or
+ * Row-level override for a {@link FilterOptionsList}, applied to plain and visual rows alike.
+ * Either:
+ * - an object applied to **every** row at every depth, or
  * - a function called per option, returning the overrides for that specific row (or
  *   `undefined`/no `reactNode` to leave the row at its default). Use this to target a
- *   single option — e.g. `(option) => option.id === 'x' ? {...} : undefined`.
+ *   single option - e.g. `(option) => option.id === 'x' ? {...} : undefined`.
  *
- * Note: a `filterOption.reactNode` render-prop function receives `props.children` — the
- * row's nested list — so hierarchical rows can be overridden without dropping their
- * `hierarchies`; re-emit `{props.children}` to keep nesting. A **static** `reactNode`
+ * A `filterOption.reactNode` render-prop function receives `props.children` - the
+ * row's nested list - so hierarchical rows can be overridden without dropping their nested
+ * `options`; re-emit `{props.children}` to keep nesting. A **static** `reactNode`
  * (fixed JSX) has nowhere to receive children and so renders without them.
  */
 export type FilterOptionOverride =
@@ -62,21 +130,147 @@ export type FilterOptionsListOverrides = ComponentOverrideProps<FilterOptionsLis
   filterOption?: FilterOptionOverride;
 };
 
+/** True when any option in the subtree is checked, at any depth. */
+function hasCheckedDescendant(options: FilterOptionData[]): boolean {
+  return options.some(
+    (option) => option.isChecked || (option.options ? hasCheckedDescendant(option.options) : false),
+  );
+}
+
+/**
+ * Resolves whether a branch is expanded, highest precedence first:
+ * 1. a toggle the user has performed on this row (`toggledIds`)
+ * 2. the row's own `defaultCollapsed`
+ * 3. auto-expand, when a descendant is checked and the default would otherwise hide it
+ * 4. the list's `defaultCollapsed`
+ *
+ * Deriving this per render - rather than seeding a state entry per branch - means branches that
+ * appear later (a facet reloads, options get filtered) pick up their default on first sight with
+ * no bookkeeping, while `toggledIds` only ever holds rows the user actually touched.
+ */
+function resolveIsExpanded({
+  id,
+  options,
+  rowDefaultCollapsed,
+  toggledIds,
+  listDefaultCollapsed,
+}: Pick<FilterOptionData, 'id'> & {
+  options: FilterOptionData[];
+  rowDefaultCollapsed?: boolean;
+  toggledIds: Record<string, boolean>;
+  listDefaultCollapsed: boolean;
+}): boolean {
+  if (Object.prototype.hasOwnProperty.call(toggledIds, id)) return toggledIds[id];
+  if (rowDefaultCollapsed !== undefined) return !rowDefaultCollapsed;
+  if (!listDefaultCollapsed) return true;
+  return hasCheckedDescendant(options);
+}
+
+/** Id of the nested list a row's toggle controls, derived from the row's own id. */
+function getHierarchyId(optionId: string): string {
+  return `${optionId}-hierarchy`;
+}
+
 /**
  * Presentational, recursive hierarchical filter list. Renders an `options` array as
- * `FilterOption` rows, recursing into each option's `hierarchies` and reusing
- * `FilterOption`'s `children` slot for nesting — so a flat list is just options with no
- * `hierarchies`. Fully controlled: selection state comes in via each option's `isChecked`,
- * and changes flow out via `onChange`.
+ * `FilterOption` rows - or `FilterOptionVisual` swatch rows for options carrying a `visual` -
+ * recursing into each option's nested `options` and reusing the row's `children` slot for
+ * nesting, so a flat list is just options with no nested `options`. Selection is fully
+ * controlled: it comes in via each option's `isChecked` and changes flow out via `onChange`.
+ *
+ * Branch expansion, by contrast, is uncontrolled: rows with nested `options` get a collapse
+ * toggle, and this component owns the open/closed state. The data supplies only the starting
+ * point (`collapsible` / `defaultCollapsed` per row, or the same two props for the whole list) -
+ * expansion has no effect outside this list, so there is nothing for a parent to synchronize.
  */
 export default function FilterOptionsList(props: FilterOptionsListProps) {
-  return <FilterOptionsListInner {...props} nested={false} />;
+  const [toggledIds, setToggledIds] = React.useState<Record<string, boolean>>({});
+  const onToggleHierarchy = React.useCallback((id: string, isExpanded: boolean) => {
+    setToggledIds((previous) => ({ ...previous, [id]: isExpanded }));
+  }, []);
+
+  return (
+    <FilterOptionsListInner
+      {...props}
+      nested={false}
+      toggledIds={toggledIds}
+      onToggleHierarchy={onToggleHierarchy}
+      filterOption={props.componentOverrides?.filterOption}
+    />
+  );
+}
+
+interface FilterOptionHierarchyToggleProps {
+  isExpanded: boolean;
+  /** Id of the nested list, or `undefined` while that list is unmounted. */
+  controlsId?: string;
+  /** The row's label, so the toggle reads as "Collapse Shirts" rather than bare "Collapse". */
+  displayValue: string;
+  onToggle: () => void;
 }
 
 /**
- * Internal recursive renderer. The private `nested` flag (root vs. descendant) is kept
- * off the public component so it never surfaces in the prop surface / autodocs; indentation
- * compounds automatically via DOM nesting, so a boolean is all that's needed.
+ * Collapse toggle for one row's nested list. Lives in the row's `children` slot - a sibling of
+ * the `<label>`
+ */
+function FilterOptionHierarchyToggle({
+  isExpanded,
+  controlsId,
+  displayValue,
+  onToggle,
+}: FilterOptionHierarchyToggleProps) {
+  return (
+    <button
+      type='button'
+      data-slot='filter-option-hierarchy-toggle'
+      aria-expanded={isExpanded}
+      aria-controls={controlsId}
+      aria-label={`${isExpanded ? 'Collapse' : 'Expand'} ${displayValue}`}
+      onClick={onToggle}
+      className={cn(
+        'cio-filter-option-hierarchy-toggle cio:flex cio:items-center cio:justify-center cio:h-6 cio:rounded-sm cio:cursor-pointer cio:bg-transparent cio:border-0 cio:p-0 cio:text-gray-400 cio:hover:text-gray-700 cio:outline-none cio:focus-visible:ring-ring/50 cio:focus-visible:ring-[3px]',
+        toggleFootprintClasses,
+      )}>
+      <svg
+        width='12'
+        height='8'
+        viewBox='0 0 12 8'
+        fill='none'
+        aria-hidden='true'
+        xmlns='http://www.w3.org/2000/svg'
+        className={cn(
+          'cio-filter-option-hierarchy-chevron cio:transition-transform cio:duration-250',
+          !isExpanded && 'cio:rotate-180',
+        )}>
+        <path
+          d='M1 1.5L6 6.5L11 1.5'
+          stroke='currentColor'
+          strokeWidth='1.7'
+          strokeLinecap='round'
+          strokeLinejoin='round'
+        />
+      </svg>
+    </button>
+  );
+}
+
+type FilterOptionsListInnerProps = FilterOptionsListProps & {
+  nested: boolean;
+  toggledIds: Record<string, boolean>;
+  onToggleHierarchy: (id: string, isExpanded: boolean) => void;
+  /**
+   * The row-level override, threaded on its own rather than inside `componentOverrides`, so that
+   * only it recurses: the list-level `reactNode` would replace each nested list wholesale and
+   * break the recursion, and so stays behind at the root.
+   */
+  filterOption?: FilterOptionOverride;
+};
+
+/**
+ * Internal recursive renderer. The private props (`nested` - root vs. descendant - and the
+ * expansion state threaded down from the root) are kept off the public component so they never
+ * surface in the prop surface / autodocs; indentation compounds automatically via DOM nesting,
+ * so a boolean is all that's needed for depth.
  */
 function FilterOptionsListInner({
   options,
@@ -84,52 +278,129 @@ function FilterOptionsListInner({
   checkboxPosition,
   componentOverrides,
   className,
+  collapsible = true,
+  defaultCollapsed = false,
   nested,
+  toggledIds,
+  onToggleHierarchy,
+  filterOption,
   ...props
-}: FilterOptionsListProps & { nested: boolean }) {
+}: FilterOptionsListInnerProps) {
   const renderProps = React.useMemo(
     () => ({
       ...props,
       options,
       onChange,
       checkboxPosition,
+      collapsible,
+      defaultCollapsed,
       className,
     }),
-    [props, options, onChange, checkboxPosition, className],
+    [props, options, onChange, checkboxPosition, collapsible, defaultCollapsed, className],
+  );
+
+  // Whether any row at this level shows a toggle. Rows that don't get an equal-width spacer, so
+  // counts line up in a column instead of stepping left on the rows that have one.
+  const levelHasToggle = options.some(
+    (option) => !!option.options?.length && (option.collapsible ?? collapsible),
   );
 
   return (
     <RenderPropsWrapper props={renderProps} override={componentOverrides?.reactNode}>
       <ul
         data-slot='filter-options-list'
-        className={cn(baseClasses, nested && 'cio:pl-4', className)}
+        className={cn(baseClasses, nested && nestedListClasses, className)}
         {...props}>
         {options.map((option) => {
-          const { hierarchies, ...optionProps } = option;
-          const hasChildren = !!hierarchies?.length;
-          const filterOption = componentOverrides?.filterOption;
+          const {
+            options: nestedOptions,
+            visual,
+            startContent,
+            collapsible: rowCollapsible,
+            defaultCollapsed: rowDefaultCollapsed,
+            ...optionProps
+          } = option;
+          const hasChildren = !!nestedOptions?.length;
           const rowOverride =
             typeof filterOption === 'function' ? filterOption(option) : filterOption;
 
-          return (
-            <FilterOption
-              key={option.id}
-              {...optionProps}
+          const isCollapsible = hasChildren && (rowCollapsible ?? collapsible);
+          const isExpanded =
+            !isCollapsible ||
+            resolveIsExpanded({
+              id: option.id,
+              options: nestedOptions ?? [],
+              rowDefaultCollapsed,
+              toggledIds,
+              listDefaultCollapsed: defaultCollapsed,
+            });
+          const hierarchyId = getHierarchyId(option.id);
+
+          const rowProps = {
+            ...optionProps,
+            // `FilterOption` reports only the value it was given; the row it belongs to is added
+            // back here, where the option is still in scope.
+            onChange: (value: string) => onChange(value, option),
+            checkboxPosition,
+            componentOverrides: rowOverride,
+            className: cn(
+              nested && nestedRowClasses,
+              hasChildren && 'cio:flex-wrap cio:items-center',
+            ),
+          };
+
+          const nestedList = hasChildren && isExpanded && (
+            <FilterOptionsListInner
+              nested
+              id={isCollapsible ? hierarchyId : undefined}
+              options={nestedOptions}
               onChange={onChange}
               checkboxPosition={checkboxPosition}
-              componentOverrides={rowOverride}
-              className={hasChildren ? 'cio:flex-col' : undefined}>
-              {hasChildren && (
-                <FilterOptionsListInner
-                  nested
-                  options={hierarchies}
-                  onChange={onChange}
-                  checkboxPosition={checkboxPosition}
-                  // Propagate only the row-level override — NOT the list-level `reactNode`,
-                  // which would replace each nested list wholesale and break recursion.
-                  componentOverrides={{ filterOption }}
+              collapsible={collapsible}
+              defaultCollapsed={defaultCollapsed}
+              toggledIds={toggledIds}
+              onToggleHierarchy={onToggleHierarchy}
+              filterOption={filterOption}
+            />
+          );
+
+          const rowChildren = (
+            <>
+              {isCollapsible && (
+                <FilterOptionHierarchyToggle
+                  isExpanded={isExpanded}
+                  // Only reference the nested list while it exists - collapsing unmounts it.
+                  controlsId={isExpanded ? hierarchyId : undefined}
+                  displayValue={option.displayValue}
+                  onToggle={() => onToggleHierarchy(option.id, !isExpanded)}
                 />
               )}
+              {levelHasToggle && !isCollapsible && (
+                <span
+                  aria-hidden='true'
+                  data-slot='filter-option-hierarchy-toggle-spacer'
+                  className={cn(
+                    'cio-filter-option-hierarchy-toggle-spacer',
+                    toggleFootprintClasses,
+                  )}
+                />
+              )}
+              {nestedList}
+            </>
+          );
+          // A `visual` missing either half is not a swatch - JS consumers can build one, so this
+          // falls back to a plain row rather than rendering an empty swatch.
+          return visual?.type && visual?.value ? (
+            <FilterOptionVisual
+              key={option.id}
+              {...rowProps}
+              visualType={visual.type}
+              visualValue={visual.value}>
+              {rowChildren}
+            </FilterOptionVisual>
+          ) : (
+            <FilterOption key={option.id} {...rowProps} startContent={startContent}>
+              {rowChildren}
             </FilterOption>
           );
         })}
diff --git a/src/index.ts b/src/index.ts
index 6203a98..ccbff16 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -27,5 +27,6 @@ export type {
   FilterOptionsListOverrides,
   FilterOptionOverride,
   FilterOptionData,
+  FilterOptionVisualData,
 } from '@/components/filter-options-list';
 export * from '@/types';
diff --git a/src/stories/components/FilterOptionsList/FilterOptionsList.stories.tsx b/src/stories/components/FilterOptionsList/FilterOptionsList.stories.tsx
index 29b8a98..cf7f849 100644
--- a/src/stories/components/FilterOptionsList/FilterOptionsList.stories.tsx
+++ b/src/stories/components/FilterOptionsList/FilterOptionsList.stories.tsx
@@ -38,13 +38,13 @@ const hierarchicalOptions: FilterOptionData[] = [
     optionValue: 'apparel',
     displayValue: 'Apparel',
     displayCountValue: '1240',
-    hierarchies: [
+    options: [
       {
         id: 'apparel-mens',
         optionValue: 'apparel/mens',
         displayValue: "Men's",
         displayCountValue: '540',
-        hierarchies: [
+        options: [
           {
             id: 'apparel-mens-shirts',
             optionValue: 'apparel/mens/shirts',
@@ -65,7 +65,7 @@ const hierarchicalOptions: FilterOptionData[] = [
         optionValue: 'apparel/women',
         displayValue: "Women's",
         displayCountValue: '700',
-        hierarchies: [
+        options: [
           {
             id: 'apparel-women-dresses',
             optionValue: 'apparel/women/dresses',
@@ -82,7 +82,7 @@ const hierarchicalOptions: FilterOptionData[] = [
     displayValue: 'Electronics',
     displayCountValue: '860',
     isChecked: true,
-    hierarchies: [
+    options: [
       {
         id: 'electronics-phones',
         optionValue: 'electronics/phones',
@@ -99,7 +99,7 @@ const hierarchicalOptions: FilterOptionData[] = [
   },
 ];
 
-// Options with no `hierarchies` render as a flat list — flatness is a property of the data.
+// Options with no nested `options` render as a flat list — flatness is a property of the data.
 const flatOptions: FilterOptionData[] = [
   { id: 'white', optionValue: 'white', displayValue: 'White', displayCountValue: '1572' },
   { id: 'black', optionValue: 'black', displayValue: 'Black', displayCountValue: '685' },
@@ -113,6 +113,87 @@ const flatOptions: FilterOptionData[] = [
   },
 ];
 
+// An option renders as a swatch row (`FilterOptionVisual`) as soon as it carries a
+// `visual` — there is no `isVisual` flag to set; it is derived.
+const visualOptions: FilterOptionData[] = [
+  {
+    id: 'visual-white',
+    optionValue: 'white',
+    displayValue: 'White',
+    displayCountValue: '1572',
+    visual: { type: 'color', value: '#FFFFFF' },
+  },
+  {
+    id: 'visual-black',
+    optionValue: 'black',
+    displayValue: 'Black',
+    displayCountValue: '685',
+    visual: { type: 'color', value: '#000000' },
+    isChecked: true,
+  },
+  {
+    id: 'visual-red',
+    optionValue: 'red',
+    displayValue: 'Red',
+    displayCountValue: '646',
+    visual: { type: 'color', value: '#EF4444' },
+  },
+  {
+    id: 'visual-pattern',
+    optionValue: 'constructor',
+    displayValue: 'Constructor',
+    displayCountValue: '128',
+    visual: {
+      type: 'image',
+      value: 'https://constructor.com/hubfs/constructor-favicon-2024-1.svg',
+    },
+  },
+];
+
+// Visual and plain options are the same shape, so they nest and mix at any depth: a plain
+// parent row with visual children, and a visual parent with visual children.
+const mixedOptions: FilterOptionData[] = [
+  {
+    id: 'mixed-color',
+    optionValue: 'color',
+    displayValue: 'Color',
+    displayCountValue: '2903',
+    options: [
+      {
+        id: 'mixed-blue',
+        optionValue: 'blue',
+        displayValue: 'Blue',
+        displayCountValue: '394',
+        visual: { type: 'color', value: '#3B82F6' },
+        options: [
+          {
+            id: 'mixed-navy',
+            optionValue: 'navy',
+            displayValue: 'Navy',
+            displayCountValue: '112',
+            visual: { type: 'color', value: '#1E3A8A' },
+            isChecked: true,
+          },
+        ],
+      },
+      {
+        id: 'mixed-green',
+        optionValue: 'green',
+        displayValue: 'Green',
+        displayCountValue: '221',
+        visual: { type: 'color', value: '#22C55E' },
+      },
+    ],
+  },
+  {
+    id: 'mixed-size',
+    optionValue: 'size',
+    displayValue: 'Size',
+    displayCountValue: '860',
+    options: [{ id: 'mixed-small', optionValue: 'small', displayValue: 'Small' }],
+  },
+];
+
 export const Default: Story = {
   args: {
     options: hierarchicalOptions,
@@ -134,6 +215,84 @@ export const DeepHierarchy: Story = {
   },
 };
 
+// Swatch rows: colors and an image, driven purely by each option's `visual` in the data.
+export const Visual: Story = {
+  args: {
+    options: visualOptions,
+  },
+};
+
+// Plain and visual rows in one tree. `checkboxPosition` is set explicitly here because the
+// two row types default differently (plain → left, visual → right).
+export const MixedVisualAndPlain: Story = {
+  args: {
+    options: mixedOptions,
+    checkboxPosition: 'left',
+  },
+};
+
+// --- Collapsing branches -----------------------------------------------------------
+// Rows with nested `options` carry a toggle for their own nested list — it collapses branches
+// *within* the list, never the list itself. Expansion is uncontrolled: the data sets the
+// starting point and the component owns it from there, since nothing outside the list depends
+// on which branches are open.
+
+// Every branch starts closed — except the path down to a checked option, which is expanded
+// automatically so an applied filter is never hidden. Here "Pants" is checked, so Apparel and
+// Men's open; Women's and Electronics stay closed.
+export const CollapsedByDefault: Story = {
+  args: {
+    options: hierarchicalOptions,
+    defaultCollapsed: true,
+  },
+};
+
+// Opting out entirely: branches render exactly as they did before collapsing existed.
+export const NonCollapsibleHierarchies: Story = {
+  args: {
+    options: hierarchicalOptions,
+    collapsible: false,
+  },
+};
+
+// Per-row control wins over the list-level defaults, so one tree can mix all three states:
+// a branch pinned open with no toggle, a branch that starts closed, and a branch left at the
+// list default.
+const perRowCollapseOptions: FilterOptionData[] = [
+  {
+    id: 'pinned',
+    optionValue: 'pinned',
+    displayValue: 'Always open (no toggle)',
+    collapsible: false,
+    options: [
+      { id: 'pinned-a', optionValue: 'pinned/a', displayValue: 'Child A' },
+      { id: 'pinned-b', optionValue: 'pinned/b', displayValue: 'Child B' },
+    ],
+  },
+  {
+    id: 'starts-closed',
+    optionValue: 'starts-closed',
+    displayValue: 'Starts collapsed',
+    defaultCollapsed: true,
+    options: [
+      { id: 'closed-a', optionValue: 'closed/a', displayValue: 'Child C' },
+      { id: 'closed-b', optionValue: 'closed/b', displayValue: 'Child D' },
+    ],
+  },
+  {
+    id: 'list-default',
+    optionValue: 'list-default',
+    displayValue: 'Follows the list default',
+    options: [{ id: 'default-a', optionValue: 'default/a', displayValue: 'Child E' }],
+  },
+];
+
+export const PerRowCollapseControl: Story = {
+  args: {
+    options: perRowCollapseOptions,
+  },
+};
+
 // `componentOverrides` supports three levels of customization, each demonstrated below:
 //   1. The whole list  — `reactNode` replaces the entire `<ul>`.
 //   2. Every option    — `filterOption` as an object overrides every row at every depth.
@@ -198,7 +357,7 @@ export const AllOptionsOverrideExample: Story = {
 // `filterOption` as a function is called per option; return overrides only for the rows
 // you want to customize and `undefined` for the rest. The matched row here is a parent,
 // and re-emitting `props.children` keeps its nested list, so the override customizes one
-// row without collapsing the hierarchy beneath it.
+// row without collapsing the branch beneath it.
 const singleOptionOverride: FilterOptionsListOverrides = {
   filterOption: (option) =>
     option.id === 'apparel-mens'

From edb383f0794fe8aab810da23fda23e2b218d82b9 Mon Sep 17 00:00:00 2001
From: Sherzod Baxodirov <sherzod.baxodirov@constructor.io>
Date: Wed, 19 Aug 2026 20:16:26 +0500
Subject: [PATCH 4/4] chore: update cspell.json

---
 cspell.json | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/cspell.json b/cspell.json
index c83dd81..0426ec8 100644
--- a/cspell.json
+++ b/cspell.json
@@ -18,6 +18,7 @@
     "Autodocs",
     "autodocs",
     "Embla",
-    "svgs"
+    "svgs",
+    "toggleable"
   ]
 }