CynosureComponents / Structure
DocumentViewport
A scrolling, zoomable document of pages, rendering only the pages near the view.
When to useLink to "When to use"
- Documents of pages: PDFs, scans, slides, where people read, zoom and work on a page.
Use something else when:
- it is one image to compare: CompareSlider
- it is a long list of rows: VirtualList
UsageLink to "Usage"
tsx
<ZoomControls zoom={zoom} percent={scale * 100} onZoomChange={setZoom} />
<DocumentViewport
label="Contract.pdf"
pages={pages}
zoom={zoom}
onZoomChange={setZoom}
onScaleChange={setScale}
renderPage={({ id, scale, visibleRect }) => <PageCanvas id={id} scale={scale} only={visibleRect} />}
/>pages are { id, width, height } at 100%. renderPage draws a page at scale; for very large pages draw only visibleRect. Use onCurrentPageChange to keep a page rail in step, and scrollTo (with a new nonce each time) to go to a page or centre a spot on it.
PropsLink to "Props"
| Prop | What it does | Type | Default |
|---|---|---|---|
labelRequired | Names the viewport ("Document", "Contract.pdf"). | string | |
pagesRequired | The pages, top to bottom, each with its size at 100%. | readonly ViewportPage[] | |
renderPageRequired | Draws one page. Called for each page in or near the view. | (page: RenderPageProps) => ReactNode | |
zoom | The zoom setting, when you control it: fit width, fit page or a percent. | ZoomSetting | |
defaultZoom | Default fit-width. | ZoomSetting | fit-width |
onZoomChange | Gestures and keys ask for a percent. | ((zoom: ZoomSetting) => void) | |
onVisiblePagesChange | The pages in view, top to bottom. | ((ids: string[]) => void) | |
onCurrentPageChange | The page with the most of itself in view. | ((id: string | null) => void) | |
onScaleChange | The scale the zoom came to (fit modes depend on the viewport). | ((scale: number) => void) | |
scrollTo | Scrolls to a page, or to a rect on it. A new nonce scrolls again. | ScrollRequest | |
labels | Replace the built-in English text: page names and the zoom announcement. | Partial<DocumentViewportLabels> | |
className | Added to the scrolling root element, for layout. | string | |
style | Layout only (give it a height). Restyle through --cy-document-viewport-* tokens. | CSSProperties |
Generated from the type definitions in @arshad-shah/cynosure 0.5.0.
Behaviour and accessibilityLink to "Behaviour and accessibility"
- Roles: a named region and tab stop; each page is a group named "Page 3 of 12". Go-to-page with
scrollTo.focusmoves focus to the page. - Zoom: Ctrl/Cmd+wheel or a pinch zooms around the pointer; Ctrl/Cmd and =, - or 0 zoom in, out and to 100% while focus is inside. Changes are announced ("Zoom 125%").
- Pan: hold Space and drag with a mouse or pen; one finger scrolls.
| Key | Does |
|---|---|
| Arrow keys, Page Up/Down | Scroll |
| Ctrl/Cmd + = / - | Zoom in / out a step |
| Ctrl/Cmd + 0 | 100% |
| Space (held) + drag | Pan |
ThemingLink to "Theming"
Tokens: --cy-document-viewport-background, --cy-document-viewport-gap and --cy-document-viewport-page-shadow.
RelatedLink to "Related"
These examples run Cynosure 0.5.0 (commit 50ce30b), the version on npm.