> For the complete documentation index, see [llms.txt](https://docs.rowsncolumns.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.rowsncolumns.app/configuration/features/slicers.md).

# Slicers

Slicers let users filter table data using an interactive floating control on the sheet.

## Basic setup

Use `slicers` state + `onChangeSlicers` with `useSpreadsheetState`, then pass slicer props and handlers to `CanvasGrid`.

```tsx
import { useState } from "react";
import {
  CanvasGrid,
  Slicer,
  SlicerComponent,
  SlicerComponentProps,
} from "@rowsncolumns/spreadsheet";
import { useSpreadsheetState } from "@rowsncolumns/spreadsheet-state";

const Example = () => {
  const [slicers, onChangeSlicers] = useState<Slicer[]>([
    {
      slicerId: "slicer-1",
      position: {
        sheetId: 1,
        overlayPosition: {
          anchorCell: { rowIndex: 2, columnIndex: 12 },
          widthPixels: 150,
          heightPixels: 200,
          offsetXPixels: 10,
          offsetYPixels: 10,
        },
      },
      spec: {
        type: "table",
        tableIds: [1],
        columnIndex: 1,
      },
    },
  ]);

  const {
    onMoveSlicer,
    onResizeSlicer,
    onDeleteSlicer,
    onUpdateSlicer,
    onCreateSlicer,
    onRequestEditSlicer,
  } = useSpreadsheetState({
    slicers,
    onChangeSlicers,
  });

  return (
    <CanvasGrid
      slicers={slicers}
      onMoveSlicer={onMoveSlicer}
      onResizeSlicer={onResizeSlicer}
      onDeleteSlicer={onDeleteSlicer}
      onRequestEditSlicer={onRequestEditSlicer}
      getSlicerComponent={(props: SlicerComponentProps) => {
        return <SlicerComponent {...props} />;
      }}
    />
  );
};
```

## Programmatically create a slicer

You can create slicers using `onCreateSlicer`.

```tsx
onCreateSlicer({
  slicerId: "slicer-2",
  position: {
    sheetId: 1,
    overlayPosition: {
      anchorCell: { rowIndex: 5, columnIndex: 12 },
      widthPixels: 160,
      heightPixels: 220,
      offsetXPixels: 0,
      offsetYPixels: 0,
    },
  },
  spec: {
    type: "table",
    tableIds: [1],
    columnIndex: 2,
  },
});
```

## Available slicer handlers from `useSpreadsheetState`

* `onCreateSlicer`
* `onUpdateSlicer`
* `onDeleteSlicer`
* `onMoveSlicer`
* `onResizeSlicer`
* `onRequestEditSlicer`

All handlers integrate with undo/redo history when `onChangeSlicers` is provided.

## Notes

* Two slicer types ship: **table-backed** (`spec.type = "table"`, connects to one or more `TableView`s by id) and **pivot-backed** (`spec.type = "pivot"`, connects to one or more pivot tables by id + a field name).
* Pivot-backed slicers read distinct values from the bound pivot's source range (column matching `fieldName`). Selection routes through the new `onFilterPivot` callback — wire it to `usePivot.applySlicerSelectionToPivots`:

  ```tsx
  const { applySlicerSelectionToPivots } = usePivot({ /* … */ });

  return (
    <CanvasGrid
      slicers={slicers}
      onFilterPivot={applySlicerSelectionToPivots}
      pivotTables={pivotTables}
      /* … */
    />
  );
  ```
* For custom rendering, provide your own component through `getSlicerComponent`.
* XLSX round-trip: **table-backed slicers** ship in full; **pivot-backed** OLAP cube cache export is deferred (the slicer UI works on import + during a session, but a saved-and-reopened file may need to refresh from source).