--- title: "Canvas" description: "Clover's own renderer for IIIF Canvases: images, video and sound on one pan and zoom surface, on its own or in a Root." url: https://clover.iiif.library.northwestern.edu/docs/canvas version: "4" --- # Canvas \ (web components: \)46 kB loaded by a page with it alone to first view, gzipped (web components: 87 kB loaded by a page with it alone to first view, styles included, gzipped) Clover’s own renderer for IIIF Canvases: images, video and sound on one pan and zoom surface. > **Example**: a live example on the page, showing sample IIIF data. What it shows is demonstration content, not about Clover; its code, where the page gives it, follows. **React** ```jsx
``` **Web components** ```html
``` ## API reference Draws the Presentation 4 Canvases you hand it, or loads one itself (`iiifContent` (web components: `iiif-content`)), with WebGL2, else Canvas2D. Inside a `Root` (web components: ``), given nothing to draw, it shows the Root’s current view. It fills its parent, so give the parent a height. It is experimental: its API may change in any release. A plain wheel scrolls the page, unless `options.gestures.scrollToZoom` is on. **React** | Prop | Type | Default | Description | | ------------------------ | ------------------------------------------------------------------------------- | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `iiifContent` | `string \| object` | — | A Canvas to load and draw, or a Manifest’s first: URL or JSON. | | `canvases` | `object[]` | The Root’s view | Presentation 4 Canvases, drawn together; `toPresentation4()` upgrades older ones. | | `body` | `object \| object[]` | — | IIIF painting bodies to draw; they win over `src`. | | `src` | `string \| string[]` | — | Image URLs, or image services with `isTiledImage`. | | `isTiledImage` | `boolean` | `false` | Read each `src` as an image service: its base URI or `info.json`. | | `viewingDirection` | `"left-to-right" \| "right-to-left" \| "top-to-bottom" \| "bottom-to-top"` | `"left-to-right"` | How several Canvases line up; in a `Root`, the Manifest’s. | | `label` | language map or `string` | The Canvas’s label | The viewport’s accessible name. | | `partOf` | language map or `string` | The Manifest’s label | Under the title of a lone recording of sound, which plays as a [player](https://clover.iiif.library.northwestern.edu/docs/timeline). | | `language` | `string` | The reader’s, or the Root’s | The language to read labels, Choices and annotations in. | | `highContrast` | `boolean` | `false` | Clover’s higher-contrast mode: the accent kept to rings, outlines and marks, never under words or a glyph. Inside a `Root`, the Root’s too; on wherever the reader’s system asks for more contrast. | | `controls` | `boolean \| { zoom, fullPage, rotation, reset, annotations, information, map }` | `true` | All of Clover’s controls, none, or all but those set `false`. | | `navPlace` | `object` | — | Where it is, the Manifest’s `navPlace`, which its Map control shows where its Canvases have none. In a `Root`, the Root’s Manifest’s. | | `navigator` | `boolean` | `false` | An overview of the whole image, to press or drag in. | | `placeholder` | `boolean` | `true` | Open on the Canvas’s `placeholderContainer`, where it has one. | | `options` | `object` | — | `backend`, `gestures`, `maxZoomPixelRatio`, `minZoomImageRatio`, `animationTime`, `hideDelay`, `animation`, `media`, `request`. | | `controlButtons` | `object` | — | Components of your own for `zoomIn`, `zoomOut`, `fullPage`, `rotateRight`, `rotateLeft`, `reset`, `choice`. | | `onReady` | `(handle: CanvasHandle) => void` | — | Once laid out, a handle to zoom, pan and turn it. | | `onViewportChange` | `(bounds: { x, y, width, height }) => void` | — | The region in view, at most once a frame. | | `annotations` | `{ annotation, targetIndex, pageLabel?, pageId? }[]` | The loaded Canvas’s, or the Root’s | Hotspots on regions, points and shapes; whole-Canvas ones go to its information. | | `hiddenPages` | `string[]` | — | AnnotationPages (`pageId`) not drawn; its menu still lists them. | | `onPageVisibilityChange` | `(pageIds: string[], visible: boolean) => void` | — | The reader hid pages, or showed them, from the menu. | | `selectedAnnotation` | `string \| null` | — | The picked annotation, controlled; `null` picks none. | | `onAnnotationSelect` | `(id: string \| null) => void` | — | A hotspot or the menu picked one, or `null` let it go. | | `highlightedAnnotation` | `string \| null` | — | One to highlight, as hovering it in a list does. | | `onAnnotationActive` | `(id: string \| null) => void` | — | The hotspot hovered or focused, or `null`. | | `onAnnotationLink` | `(link: { id, canvasId?, manifestId? }) => void` | — | A linking hotspot was pressed; in a `Root` or with `iiifContent`, followed for you. | | `animateAnnotations` | `boolean` | `false` | Glide to a picked annotation, rather than cut to it. | | `chapters` | `{ id?, label, lang?, start, end? }[]` | The Ranges, in a `Root` | Chapters of the recording, on its seek bar and in a menu. | | `highlightedChapter` | `string \| null` | — | A chapter (`id`) to draw out on the seek bar. | | `onChapterHighlight` | `(id: string \| null) => void` | — | The chapter under the pointer on the seek bar, or `null`. | | `caption` | `string \| null` | — | The caption file (`id`) to show while captions are on. | | `onCaptionChange` | `(caption: { id, language? } \| null) => void` | — | The reader chose a caption file, or Off (`null`). | | `onMediaElement` | `(element: HTMLVideoElement \| null) => void` | — | The recording’s element, for a transcript of your own. | | `onEnded` | `() => void` | — | Playback reached the end: a cue to move on. | | `manifestId` | `string` | — | The Canvases’ Manifest: a new one clears the Canvas at once. | | `instanceId` | `string` | — | A stable id; a new one remounts the renderer. | | `className` | `string` | — | Added to `clover-canvas`, on its `figure`. | | `children` | `ReactNode` | — | Your own controls, after Clover’s. | **Web components** ### `` Clover's renderer for images, video and sound. Alone, it draws what it is given: a IIIF resource by URL (a Manifest gives its first Canvas), image URLs, or Canvases as a property. Inside a clover-root, given nothing, the root's view. As tall as --clover-body-height (60vh) or its own style. | Name | Type | Default | Description | | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `iiif-content` | `string` | — | A Canvas, a Manifest (its first Canvas) or a content state, by URL, in any Presentation version. | | `src` | `string` | — | An image's URL; with tiled, a IIIF Image API service's (its base URI or info.json). | | `tiled` | `boolean` | `false` | Read src as a IIIF Image API service. | | `label` | `string` | — | The viewport's name, for an image given by src. A Canvas names it by its own label. | | `language` | `string` | — | The language to read IIIF text in. | | `high-contrast` | `boolean` | `false` | Clover's higher-contrast mode, for what is inside: the accent kept to rings, outlines and marks, never under words or a glyph, where the controls' dark fill takes its place, edged in the accent. On wherever the reader's system asks for more contrast, too. | | `controls` | `boolean` | `true` | "false" leaves out the controls over the Body. | | `navigator` | `boolean` | `false` | A small map of the whole image, while zoomed in. | | `placeholder` | `boolean` | `true` | "false" opens a Canvas straight away, past its placeholderContainer. | | `viewing-direction` | `"left-to-right" \| "right-to-left" \| "top-to-bottom" \| "bottom-to-top"` | `left-to-right` | How several Canvases (a spread) are laid out, in reading order. | | `animate-annotations` | `boolean` | `false` | Glide to a picked annotation, rather than frame it in one cut. A reader who asks for reduced motion gets the cut. | | `.handle` | `CloverCanvasHandle \| null` | — | Read-only. The Canvas's handle once its view is laid out (clover-ready), as onReady hands it in React: the camera and its coordinates (handle.zoomBy(2), handle.home()). Null before. | | `.iiifContent` | `string \| Record \| null` | — | As a property: What to load and draw, as a URL or a IIIF resource. | | `.canvases` | `Record[] \| null` | — | Presentation 4 Canvases to draw, one or several shown together (a spread). | | `.src` | `string \| string[] \| null` | — | As a property: Image URLs, or image services with tiled. | | `.annotations` | `Array<{ id: string; target: string; label?: string; [key: string]: unknown }> \| null` | — | Annotations to draw as hotspots, with rectangular (xywh) targets in the image's own coordinates. | | `.options` | `{ request?: { credentials?: RequestCredentials; headers?: Record; fetch?: typeof fetch }; [key: string]: unknown } \| null` | — | The Canvas's options: the request it loads with (credentials, headers, a fetch of your own), its gestures and more. | | `.controlButtons` | `CloverControlButtons \| null` | — | The Body's controls, each replaced by a button you make: a function given the control's name, label and Clover's icon, returning the button. Clover keeps it named, keyed and in its state, presses the control with it, and adds its popover. | | `.controls` | `boolean \| { zoom?: boolean; fullPage?: boolean; rotation?: boolean; reset?: boolean; annotations?: boolean; information?: boolean; map?: boolean; [option: string]: unknown } \| null` | — | As a property: Which of the Body's controls it shows, as Canvas's controls takes it: false for none, or some ({ rotation: false }), in place of the attribute. | | `clover-ready` | `{ handle: CloverCanvasHandle }` | — | An event. The view is laid out and fitted: its handle is here, and works from now on. | | `clover-annotation-select` | `{ id: string \| null }` | — | An event. The reader picked an annotation, on the Body or in its menu; null when they let it go. | | `clover-annotation-active` | `{ id: string \| null }` | — | An event. An annotation is hovered or focused; null when none is. | | `clover-caption-change` | `{ caption: { id: string; language?: string } \| null }` | — | An event. The reader chose a caption file in the Captions menu, or Off (null). | | `clover-ended` | `Record` | — | An event. A recording played to its end. | ## Examples ### Images Use `src` for images that are not on a Canvas: plain URLs, or IIIF image services with `isTiledImage` (web components: `tiled`), tiled from their `info.json`. > **Example**: a live example on the page, showing sample IIIF data. What it shows is demonstration content, not about Clover; its code, where the page gives it, follows. **React** ```jsx ``` **Web components** ```html ``` ### Several Canvases Hand it the Canvases to show together, a spread say; which to show, and moving between them, is yours. `groupViews` reads a Manifest’s `behavior` as the Viewer does. > **Example**: a live example on the page, showing sample IIIF data. What it shows is demonstration content, not about Clover; its code, where the page gives it, follows. **React** ```jsx const manifest = await Clover.toPresentation4(json); const views = Clover.groupViews( manifest.items, Clover.resolveBehavior(manifest.behavior), ); manifest.items[index])} label={manifest.label} />; ``` **Web components** ```html ``` ### Video and sound A Canvas of video or sound plays in Clover’s own transport, with the captions it carries. Each WebVTT file is offered for what its annotation `provides` (Presentation 4): `closedCaptions` as captions, `subtitles` or `translation` as subtitles, and a `transcript` alone only in the [Transcript](https://clover.iiif.library.northwestern.edu/docs/transcript). A file that provides nothing, as in Presentation 3, is captions. > **Example**: a live example on the page, showing sample IIIF data. What it shows is demonstration content, not about Clover; its code, where the page gives it, follows. **React** ```jsx ``` **Web components** ```html ``` ### Annotations on a recording’s time An annotation on a stretch of a recording (`#t=`) shows among its captions while that stretch plays; one with a region too (`xywh=…&t=…`) follows what it marks, frame by frame. Picking one, from the annotations menu or a list beside it, goes to its time. > **Example**: a live example on the page, showing sample IIIF data. What it shows is demonstration content, not about Clover; its code, where the page gives it, follows. **React** ```jsx ``` **Web components** ```html ``` ### Driving it `onReady` (web components: `clover-ready`) hands you a handle (`zoomBy`, `panBy`, `rotateBy`, `home`, `fitBounds` and more) to drive the view from controls of your own, and `onViewportChange` reports the region in view. > **Example**: a live example on the page, showing sample IIIF data. What it shows is demonstration content, not about Clover; its code, where the page gives it, follows. > > Loading… **React** ```jsx const canvas = useRef(null); (canvas.current = handle)} onViewportChange={(bounds) => setRegion(bounds)} /> ``` **Web components** ```html ``` ### Canvas or Body In a layout, place [`Body` (web components: ``)](https://clover.iiif.library.northwestern.edu/docs/body) rather than `Canvas` (web components: ``): it draws the Root’s view with this Canvas, and adds a height, your renderers, and the loading mark while the Root loads. A `Canvas` (web components: ``) alone in a `Root` (web components: ``) shows the same view, without them. **React** ```jsx ``` **Web components** ```html ``` ## Previous versions [Clover 3.x › Image](https://clover.iiif.library.northwestern.edu/docs/3.x/image) - `Canvas` (web components: ``) replaces `Image`, and the Viewer’s player for video and sound. - `body`, `src`, `label` and `instanceId` carry over. - `openSeadragonCallback` is `onReady` (web components: `clover-ready`), which hands you a handle. - `openSeadragonConfig` is `options` (web components: `.options`).