---
title: "Upgrading"
description: "Move from Clover 3.x, @samvera/clover-iiif, to Clover 4, @nulib/clover, in steps: the package, its imports, the Viewer's props and the other components."
url: https://clover.iiif.library.northwestern.edu/docs/upgrading
version: "4"
---

# 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.

\[x]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.

**React**

### Swap the package

```bash
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.

**React**

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

### Move the options to props

Clover 3.x took most settings in one `options` (web components: `.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:

**React**

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

In Clover 4:

**React**

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

The others move the same way:

| Clover 3.x                                          | Clover 4                                                                                                                                                  |
| --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `canvasIdCallback`                                  | `onCanvasChange` (web components: `clover-canvas-change`)                                                                                                 |
| `contentStateCallback`                              | `onContentStateChange` (web components: `clover-content-state-change`) ([Content State](https://clover.iiif.library.northwestern.edu/docs/content-state)) |
| `iiifContentSearchQuery={{ q }}`                    | `searchQuery` (web components: `search-query`)                                                                                                            |
| `customDisplays`                                    | `renderers` (web components: `.renderers`)                                                                                                                |
| `customTheme`                                       | CSS custom properties ([Styling](https://clover.iiif.library.northwestern.edu/docs/styling))                                                              |
| `plugins`                                           | A `Tab` (web components: `<clover-tab>`) of your own ([Panel](https://clover.iiif.library.northwestern.edu/docs/panel))                                   |
| `options.canvasHeight`                              | `--clover-body-height`, in your CSS                                                                                                                       |
| `options.showTitle`                                 | `header`                                                                                                                                                  |
| `options.showDownload`                              | `download`                                                                                                                                                |
| `options.informationPanel.open`                     | `defaultPanelOpen` (web components: `panel-open`)                                                                                                         |
| `options.informationPanel.renderAbout` and the rest | `panelSections` (web components: `panel-sections`), the sections to keep                                                                                  |
| `options.withCredentials`, `options.requestHeaders` | `request` (web components: `.request`), its `credentials` and `headers`                                                                                   |
| `options.openSeadragon`                             | `canvasOptions` (web components: `.canvasOptions`) ([Interaction](https://clover.iiif.library.northwestern.edu/docs/canvas#interaction))                  |
| `options.map`                                       | Nothing: the Panel shows the Map by itself                                                                                                                |

**Web components**

### Install the package

```bash
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.

```js
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.

```html
<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>`](https://clover.iiif.library.northwestern.edu/docs/canvas).

**Web components**

### 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.

```html
<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.

```html
<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>`](https://clover.iiif.library.northwestern.edu/docs/canvas).

### Replace the other components

The Slider is [`Items` (web components: `<clover-items>`)](https://clover.iiif.library.northwestern.edu/docs/items), the Image is [`Canvas` (web components: `<clover-canvas>`)](https://clover.iiif.library.northwestern.edu/docs/canvas), and the primitives are components of the same names, which read the resource from the `Root` (web components: `<clover-root>`) around them. The [Technical overview](https://clover.iiif.library.northwestern.edu/docs/technical#coming-from-clover-3x) lists each, and the page of each component that replaces one ends with what changed.

## Next

- [Viewer Its templates, and every prop.](https://clover.iiif.library.northwestern.edu/docs/viewer)
- [Composing Layouts of your own, from the components and hooks.](https://clover.iiif.library.northwestern.edu/docs/composing)
- [Styling Colors, sizes and classes, in place of a theme.](https://clover.iiif.library.northwestern.edu/docs/styling)
- [Clover 3.x The deprecated version's docs, kept for reference.](https://clover.iiif.library.northwestern.edu/docs/deprecated-versions)