superdoc-dev · caio-pizzol · Jun 5, 2026 · May 28, 2026 · May 28, 2026 · May 28, 2026
@@ -313,6 +313,7 @@ Snapshot values match the format you pass to `execute()`. What you read is what
 | `redo` | — | — |
 | `ruler` | — | — |
 | `zoom` | number (e.g. `125`) | number |
+| `zoom-fit-width` | none | none |
 | `document-mode` | `'editing'` \| `'suggesting'` \| `'viewing'` | mode string |
 
 ### Track changes

@@ -187,6 +187,19 @@ await ui.document.export({ exportType: ['docx'], commentsType: 'external', trigg
 await ui.document.replaceFile(file);
 ```
 
+### `ui.zoom`
+
+Zoom state, viewport metrics, and the two mutations. The snapshot updates on value changes, mode-only transitions, and viewport metric updates.
+
+```ts
+ui.zoom.getSnapshot();          // { mode, value, fitZoom, min, max, metrics }
+ui.zoom.observe((snapshot) => {});
+ui.zoom.set(125);               // numeric zoom; switches the host to manual mode
+ui.zoom.setMode('fit-width');   // continuous fit to the available width
+```
+
+In React, `useSuperDocZoom()` returns the same snapshot plus bound `set` / `setMode` actions. The toolbar registry also exposes a `zoom-fit-width` toggle command for custom toolbars.
+
 ### `ui.selection`
 
 Live slice, capture, restore, painted geometry.

@@ -117,7 +117,7 @@ Common ids you'll wire to buttons:
 | Style | `linked-style`, `clear-formatting`, `copy-format` |
 | History | `undo`, `redo` |
 | Tracked changes | `track-changes-accept-selection`, `track-changes-reject-selection` |
-| View | `ruler`, `zoom`, `document-mode` |
+| View | `ruler`, `zoom`, `zoom-fit-width`, `document-mode` |
 | Tables | `table-insert`, `table-add-row-before`, `table-add-row-after`, `table-delete-row`, `table-add-column-before`, `table-add-column-after`, `table-delete-column`, `table-merge-cells`, `table-split-cell`, `table-delete` |
 | Insert | `image` |
 

@@ -561,6 +561,68 @@ new SuperDoc({
   </CodeGroup>
 </ParamField>
 
+<ParamField path="zoom" type="Object">
+  Zoom behavior for the document. Use `mode: 'fit-width'` to keep DOCX and PDF documents fitted to the available container width. Calling `setZoom()` switches back to manual zoom.
+
+  <Expandable title="properties" defaultOpen>
+    <ParamField path="zoom.initial" type="number" default="100">
+      Initial zoom level as a percentage. In `fit-width` mode, this is the paint zoom until the first fit computes.
+    </ParamField>
+    <ParamField path="zoom.mode" type="'manual' | 'fit-width'" default="'manual'">
+      Starting zoom mode. `'manual'` holds the current value. `'fit-width'` keeps the document fitted to the container.
+    </ParamField>
+    <ParamField path="zoom.fitWidth" type="Object">
+      Bounds and padding for the applied fit-width zoom.
+      <Expandable title="properties">
+        <ParamField path="zoom.fitWidth.min" type="number" default="10">
+          Lower bound for the applied zoom percentage.
+        </ParamField>
+        <ParamField path="zoom.fitWidth.max" type="number" default="100">
+          Upper bound for the applied zoom percentage. The default never enlarges the document past its natural size; raise it to let wide containers scale the page up.
+        </ParamField>
+        <ParamField path="zoom.fitWidth.padding" type="number" default="0">
+          Horizontal padding in pixels reserved inside the available width before computing the fit.
+        </ParamField>
+      </Expandable>
+    </ParamField>
+  </Expandable>
+
+  For custom behavior, listen to [`viewport-change`](/editor/superdoc/events#viewport-change) and call `setZoom()` yourself.
+
+  <CodeGroup>
+
+  ```javascript Usage
+  const superdoc = new SuperDoc({
+    selector: '#editor',
+    document: file,
+    zoom: {
+      mode: 'fit-width',
+      fitWidth: { min: 35, max: 100, padding: 24 },
+    },
+  });
+  ```
+
+  ```javascript Full Example
+  import { SuperDoc } from 'superdoc';
+  import 'superdoc/style.css';
+
+  const superdoc = new SuperDoc({
+    selector: '#editor',
+    document: yourFile,
+    zoom: {
+      initial: 100,
+      mode: 'fit-width',
+      fitWidth: { min: 35, max: 100, padding: 24 },
+    },
+    onZoomChange: ({ zoom, mode }) => {
+      console.log(`Zoom is now ${zoom}% (${mode})`);
+    },
+  });
+  ```
+
+  </CodeGroup>
+</ParamField>
+
 <ParamField path="layoutMode" type="string" deprecated>
   <Warning>**Removed in v1.0**: Use `viewOptions.layout` instead. `'paginated'` → `'print'`, `'responsive'` → `'web'`.</Warning>
 </ParamField>
@@ -684,6 +746,26 @@ All handlers are optional functions in the configuration:
   ```
 </ParamField>
 
+<ParamField path="onZoomChange" type="function">
+  Called when zoom changes from `setZoom()`, the toolbar zoom control, or `fit-width` mode.
+
+  ```javascript
+  onZoomChange: ({ zoom, mode }) => {
+    setZoomIndicator(zoom, mode);
+  }
+  ```
+</ParamField>
+
+<ParamField path="onViewportChange" type="function">
+  Called when the fit-width calculation changes. Pixel-level width jitter is deduped. `getViewportMetrics()` always reads the latest measurements.
+
+  ```javascript
+  onViewportChange: ({ availableWidth, documentWidth, fitZoom }) => {
+    updateFitIndicator({ availableWidth, documentWidth, fitZoom });
+  }
+  ```
+</ParamField>
+
 <ParamField path="onTrackedChangeBubbleAccept" type="function">
   Custom handler for accepting tracked changes from comment bubbles. Replaces default accept behavior when provided.
 

@@ -440,12 +440,12 @@ superdoc.on('pagination-update', ({ totalPages, superdoc }) => {
 
 ### `zoomChange`
 
-When the zoom level changes via `setZoom()`.
+When the zoom level changes, from any source: `setZoom()`, the toolbar zoom control, or [`fit-width` mode](/editor/superdoc/configuration#param-zoom). The payload carries the value and the mode that produced it. Also available as the `onZoomChange` config callback.
 
 <CodeGroup>
 ```javascript Usage
-superdoc.on('zoomChange', ({ zoom }) => {
-  console.log(`Zoom: ${zoom}%`);
+superdoc.on('zoomChange', ({ zoom, mode }) => {
+  console.log(`Zoom: ${zoom}% (${mode})`);
 });
 ```
 
@@ -458,8 +458,41 @@ const superdoc = new SuperDoc({
   document: yourFile,
 });
 
-superdoc.on('zoomChange', ({ zoom }) => {
-  console.log(`Zoom: ${zoom}%`);
+superdoc.on('zoomChange', ({ zoom, mode }) => {
+  console.log(`Zoom: ${zoom}% (${mode})`);
+});
+```
+</CodeGroup>
+
+### `viewport-change`
+
+When the fit-width calculation changes. Pixel-level width changes that do not affect the rounded fit are deduped. `getViewportMetrics()` always reads the latest measurements.
+
+- `availableWidth` - container width in pixels, minus the comments sidebar when visible
+- `documentWidth` - the widest document page width in pixels at 100% zoom (zoom-independent; DOCX from laid-out pages with page-styles fallback, PDF from rendered pages)
+- `fitZoom` - the unclamped zoom percentage that fits the page into the available width
+
+HTML documents reflow to the container, so an HTML-only instance reports no metrics.
+
+For most use cases, prefer [`zoom.mode: 'fit-width'`](/editor/superdoc/configuration#param-zoom). Subscribe to this event only when you want to apply custom zoom behavior.
+
+<CodeGroup>
+```javascript Usage
+superdoc.on('viewport-change', ({ fitZoom }) => {
+  superdoc.setZoom(Math.min(100, Math.max(35, fitZoom)));
+});
+```
+
+```javascript Full Example
+import { SuperDoc } from 'superdoc';
+import 'superdoc/style.css';
+
+const superdoc = new SuperDoc({
+  selector: '#editor',
+  document: yourFile,
+  onViewportChange: ({ availableWidth, documentWidth, fitZoom }) => {
+    console.log(`Need ${fitZoom}% to fit ${documentWidth}px into ${availableWidth}px`);
+  },
 });
 ```
 </CodeGroup>

@@ -538,7 +538,7 @@ const superdoc = new SuperDoc({
 
 ### `setZoom`
 
-Set the zoom level for all documents. Propagates to all presentation editors, PDF viewers, and whiteboard layers.
+Set an explicit zoom level and switch zoom mode to `manual`. Use `setZoomMode('fit-width')` to turn automatic fitting back on.
 
 <ParamField path="percent" type="number" required>
   Zoom level as a percentage (e.g., `100`, `150`, `200`). Must be a positive finite number.
@@ -560,15 +560,106 @@ const superdoc = new SuperDoc({
   onReady: ({ superdoc }) => {
     superdoc.setZoom(150);
 
-    superdoc.on('zoomChange', ({ zoom }) => {
-      console.log(`Zoom changed to ${zoom}%`);
+    superdoc.on('zoomChange', ({ zoom, mode }) => {
+      console.log(`Zoom changed to ${zoom}% (${mode})`);
     });
   },
 });
 ```
 
 </CodeGroup>
 
+### `setZoomMode`
+
+Switch between manual zoom and automatic fit-width zoom. `'fit-width'` keeps DOCX and PDF documents fitted to the available container width, using the bounds from [`zoom.fitWidth`](/editor/superdoc/configuration#param-zoom). Calling `setZoom()` switches back to `'manual'`.
+
+<ParamField path="mode" type="'manual' | 'fit-width'" required>
+  The zoom mode to switch to.
+</ParamField>
+
+<CodeGroup>
+
+```javascript Usage
+superdoc.setZoomMode('fit-width');
+```
+
+```javascript Full Example
+import { SuperDoc } from 'superdoc';
+import 'superdoc/style.css';
+
+const superdoc = new SuperDoc({
+  selector: '#editor',
+  document: yourFile,
+  onReady: ({ superdoc }) => {
+    superdoc.setZoomMode('fit-width');
+
+    superdoc.on('zoomChange', ({ zoom, mode }) => {
+      console.log(`Zoom: ${zoom}% (${mode})`);
+    });
+  },
+});
+```
+
+</CodeGroup>
+
+### `getZoomState`
+
+Get the current zoom mode, value, latest fit calculation, and effective fit bounds.
+
+**Returns:** `SuperDocZoomState` - `{ mode, value, fitZoom, min, max }`. `fitZoom` is `null` before the first viewport measurement.
+
+<CodeGroup>
+
+```javascript Usage
+const { mode, value, fitZoom } = superdoc.getZoomState();
+```
+
+```javascript Full Example
+import { SuperDoc } from 'superdoc';
+import 'superdoc/style.css';
+
+const superdoc = new SuperDoc({
+  selector: '#editor',
+  document: yourFile,
+  onReady: ({ superdoc }) => {
+    const state = superdoc.getZoomState();
+    console.log(`Mode: ${state.mode}, value: ${state.value}%`);
+  },
+});
+```
+
+</CodeGroup>
+
+### `getViewportMetrics`
+
+Get the latest fit-width measurements. Use this when you need custom zoom behavior instead of `zoom.mode: 'fit-width'`.
+
+**Returns:** `SuperDocViewportMetrics | null` - `{ availableWidth, documentWidth, fitZoom }`, or `null` until the first measurement (editors still mounting).
+
+<CodeGroup>
+
+```javascript Usage
+const metrics = superdoc.getViewportMetrics();
+```
+
+```javascript Full Example
+import { SuperDoc } from 'superdoc';
+import 'superdoc/style.css';
+
+const superdoc = new SuperDoc({
+  selector: '#editor',
+  document: yourFile,
+  onReady: ({ superdoc }) => {
+    const metrics = superdoc.getViewportMetrics();
+    if (metrics) {
+      superdoc.setZoom(Math.min(100, metrics.fitZoom));
+    }
+  },
+});
+```
+
+</CodeGroup>
+
 ### `focus`
 
 Focus the active editor or first available.

@@ -59,6 +59,23 @@ function App() {
 <SuperDocEditor document={file} role="editor" />
 ```
 
+### Responsive zoom
+
+Pass `zoom` with `mode: 'fit-width'` to keep the document fitted to its container as it resizes. SuperDoc observes the container for you; no resize listeners needed. Calling `setZoom()` (or the user picking a percentage in the toolbar) switches back to manual mode.
+
+```jsx
+<SuperDocEditor
+  document={file}
+  zoom={{
+    mode: 'fit-width',
+    fitWidth: { min: 35, max: 100, padding: 24 },
+  }}
+  onZoomChange={({ zoom, mode }) => console.log(`Zoom: ${zoom}% (${mode})`)}
+/>
+```
+
+For custom behavior, listen to `onViewportChange` instead and apply your own zoom with `getInstance().setZoom()`. See [zoom configuration](/editor/superdoc/configuration#param-zoom).
+
 ## Handle file uploads
 
 ```jsx