Skip to Content

Upgrading

Clover 4, @nulib/clover, takes the place of Clover 3.x, @samvera/clover-iiif, which is deprecated. A page with the Viewer moves over in a few steps.

Upgrade

Choose your setup

Clover 3.x came as React components, and as a <clover-viewer> element from a script. Choose yours, and every example in these docs is written that way.

React

You build your site with React. Add Clover to your app like any other package.

Web components (npm)

Your site has a build step, but no React. Install Clover once, then use it on any page.

Web components (CDN)

Plain HTML or an embed, no build step. Paste one line into a CMS or a blog post.

Swap the package

npm uninstall @samvera/clover-iiif
npm install @nulib/clover

React 18 and 19 are supported, as they were.

Change the imports

The Viewer is the package’s default export, in place of @samvera/clover-iiif/viewer. Its styles are a stylesheet now: import it once.

import Viewer from "@nulib/clover";
import "@nulib/clover/styles.css";

Move the options to props

Clover 3.x took most settings in one options.options object. In Clover 4 each is a prop of its own, on the Viewer or its template, or a CSS custom property. In Clover 3.x:

<Viewer
  iiifContent={url}
  canvasIdCallback={setCanvasId}
  options={{
    showTitle: false,
    informationPanel: { open: false },
    withCredentials: true,
  }}
/>

In Clover 4:

<Viewer
  iiifContent={url}
  onCanvasChange={setCanvasId}
  header={false}
  defaultPanelOpen={false}
  request={{ credentials: "include" }}
/>

The others move the same way:

Clover 3.xClover 4
canvasIdCallbackonCanvasChangeclover-canvas-change
contentStateCallbackonContentStateChangeclover-content-state-change (Content State)
iiifContentSearchQuery={{ q }}searchQuerysearch-query
customDisplaysrenderers.renderers
customThemeCSS custom properties (Styling)
pluginsA Tab<clover-tab> of your own (Panel)
options.canvasHeight--clover-body-height, in your CSS
options.showTitleheader
options.showDownloaddownload
options.informationPanel.opendefaultPanelOpenpanel-open
options.informationPanel.renderAbout and the restpanelSectionspanel-sections, the sections to keep
options.withCredentials, options.requestHeadersrequest.request, its credentials and headers
options.openSeadragoncanvasOptions.canvasOptions (Interaction)
options.mapNothing: the Panel shows the Map by itself

Install the package

npm install @nulib/clover

Clover 3.x’s elements came from its script alone. Clover 4’s install as any package does.

Import the elements

Once, anywhere on the page, in place of Clover 3.x’s script. The elements bring their own styles, so there is no stylesheet to add.

import "@nulib/clover/web-components";

Name the resource

<clover-viewer> takes the resource as iiif-content. Clover 3.x’s id no longer names it.

<clover-viewer
  iiif-content="https://iiif.io/api/cookbook/recipe/0024-book-4-toc/manifest.json"
></clover-viewer>

Clover 3.x’s <clover-image> is <clover-canvas>.

Swap the script

In the page’s <head>, in place of Clover 3.x’s script from @samvera/clover-iiif. The elements bring their own styles, so there is no stylesheet to add.

<script src="https://cdn.jsdelivr.net/npm/@nulib/clover/dist/web-components/index.umd.js"></script>

Name the resource

<clover-viewer> takes the resource as iiif-content. Clover 3.x’s id no longer names it.

<clover-viewer
  iiif-content="https://iiif.io/api/cookbook/recipe/0024-book-4-toc/manifest.json"
></clover-viewer>

Clover 3.x’s <clover-image> is <clover-canvas>.

Replace the other components

The Slider is Items<clover-items>, the Image is Canvas<clover-canvas>, and the primitives are components of the same names, which read the resource from the Root<clover-root> around them. The Technical overview lists each, and the page of each component that replaces one ends with what changed.

Next