# Quick start and the container

Initialize the SDK once per app lifecycle, load a document, create a viewer in a container, listen to events, clean up. The `PDFViewer` constructor expects an `HTMLElement` container. The SDK creates its entire DOM tree inside this element. The container must have explicit dimensions — the SDK fills 100% of the container's width and height.

## Example

```ts
import { Kernstra, PDFDocument, PDFViewer, SDKMode } from '@kernstra/pdf-web-sdk';

// 1. Initialize the SDK (once per app lifecycle)
await Kernstra.init({ license: import.meta.env.KERNSTRA_LICENSE });

// 2. Load a document
const doc = await PDFDocument.fromUrl('/form.pdf');
// or: const doc = await PDFDocument.fromFile(fileInput.files[0]);
// or: const doc = await PDFDocument.fromBytes(uint8Array);

// 3. Create a viewer with configuration
const viewer = new PDFViewer(document.getElementById('container')!, doc, {
  mode: SDKMode.FULL,
  toolbar: { print: true, download: true },
  navigation: { keyboardShortcuts: true, defaultZoom: 'fit-width' },
});

// 4. Listen to events
viewer.on('pageChanged', (e) => console.log('Page:', e.pageIndex));
viewer.on('formFieldChanged', ({ field }) => console.log('Field:', field.name, field.value));

// 5. Cleanup
viewer.destroy();
await doc.close();
```

## Common mistakes

| Mistake | Result |
| --- | --- |
| Container with `height: auto` or no height | Viewer collapses to 0px |
| Container with `overflow: scroll` | Double scrollbars (the SDK has its own scroll container) |
| Container inside a flex/grid parent without `min-height: 0` | Viewer overflows |

## Recommended layout

| Selector | Rules |
| --- | --- |
| `body` | `margin: 0; height: 100vh; display: flex; flex-direction: column;` |
| `.my-header` | `height: 60px; flex-shrink: 0;` |
| `#pdf-container` | `flex: 1; overflow: hidden;` |

## Notes

**Container requirements.** The container MUST have a defined height: `<div id="pdf-container" style="width: 100%; height: 100vh;"></div>`, or via CSS `#pdf-container { width: 100%; height: calc(100vh - 60px); }` (subtract your app header). Do NOT set `overflow` — the SDK manages its own scrolling.

The SDK is responsive — when the container's width changes (window resize, mobile orientation change, sidebar toggle), the PDF re-fits while the zoom is a fit mode — `defaultZoom: 'fit-width'` or `'fit-page'`, or the user's own Fit choice, until they zoom by hand — and the whole UI re-lays-out for the new width. See [Layout](https://kernstra.com/docs/web-sdk/config/layout).

**Mobile hosts.** Two host-side requirements, both outside the SDK's control.

**1. The viewport meta tag is mandatory.** Without it a mobile browser lays the page out at ~980px and reports that width to the SDK, so the viewer picks its desktop layout on a phone and every responsive rule stays dormant. Use `<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />`. `viewport-fit=cover` is what lets the SDK's safe-area handling reach the notch and home-indicator insets. Do not add `user-scalable=no`: a two-finger pinch on the document zooms the document itself (`navigation.pinchZoom`), and the rest of your page — or the document, with that option off — keeps the browser's own pinch-zoom only without it (see [Layout](https://kernstra.com/docs/web-sdk/config/layout)).

**2. Size the container with `dvh`, not `vh`.** On mobile `100vh` is the viewport without the browser's collapsible address bar, so a `100vh` container is taller than the screen and the bottom of the viewer sits under the chrome. Use `#pdf-container { width: 100%; height: 100dvh; }` (not `100vh`).


Web page: https://kernstra.com/docs/web-sdk/guides/container