# Getting started

> Install NiiVue, show an image on a canvas, choose WebGL2 or WebGPU, change settings, and see what changed from NiiVue 0.x.

## Install

**npm**

```bash
npm install @niivue/niivue@next
```

**pnpm**

```bash
pnpm add @niivue/niivue@next
```

**Yarn**

```bash
yarn add @niivue/niivue@next
```

**Bun**

```bash
bun add @niivue/niivue@next
```

## A first viewer

Add a `<canvas>`, attach a viewer to it, and load an image:

**HTML**

```html
<canvas id="gl1"></canvas>
<script type="module">
  import NiiVue from '@niivue/niivue'

  const nv = new NiiVue()
  await nv.attachToCanvas(document.getElementById('gl1'))
  await nv.loadVolumes([{ url: '/volumes/mni152.nii.gz' }])
</script>
```

**React**

```tsx
import NiiVue from '@niivue/niivue'
import { useEffect, useRef } from 'react'

export function Viewer({ url }: { url: string }) {
  const canvasRef = useRef<HTMLCanvasElement>(null)
  const nvRef = useRef<NiiVue>(null)

  useEffect(() => {
    const canvas = canvasRef.current
    if (!canvas) return
    const nv = new NiiVue()
    nvRef.current = nv
    const attached = nv.attachToCanvas(canvas)
    return () => {
      attached.then(() => nv.destroy())
    }
  }, [])

  useEffect(() => {
    nvRef.current?.loadVolumes([{ url }])
  }, [url])

  return <canvas ref={canvasRef} />
}
```

## WebGPU or WebGL2

NiiVue uses WebGL2 by default. Ask for WebGPU with `backend`; if the browser
can't run it, NiiVue falls back to WebGL2:

```js
const nv = new NiiVue({ backend: 'webgpu' })
```

In Safari, and every browser on iOS, WebGPU is about 4x slower with
anti-aliasing on, so turn it off there:

```js
const isWebKit =
  /AppleWebKit/.test(navigator.userAgent) &&
  !/Chrome|Chromium|Edg\//.test(navigator.userAgent)
const nv = new NiiVue({ backend: 'webgpu', isAntiAlias: !isWebKit })
```

To ship one renderer, import its build instead. It's smaller, and asking it
for the other backend throws:

```js
import NiiVue from '@niivue/niivue/webgpu' // or '@niivue/niivue/webgl2'
```

## Settings

Settings are properties. Pass them to the constructor, or change them at any
time and the view redraws:

```js
import NiiVue, { SLICE_TYPE } from '@niivue/niivue'

const nv = new NiiVue({ sliceType: SLICE_TYPE.MULTIPLANAR })
nv.isColorbarVisible = true
nv.sliceType = SLICE_TYPE.RENDER
```

Each volume and mesh has its own settings, changed with `setVolume` and
`setMesh`:

```js
nv.setVolume(0, { colormap: 'hot', calMin: 2, calMax: 6 })
```

## Coming from NiiVue 0.x

This package is a rewrite. Most features carry over, but the API is
different: setter methods such as `setSliceType(v)` became properties such
as `nv.sliceType = v`. The
[migration table](https://niivue.com/docs/reference/migrating/)
lists the renames, the
[API style guide](https://github.com/niivue/mono/blob/main/packages/niivue/notes/api.md)
lists the properties by group, and
[FEATURE_PARITY.md](https://github.com/niivue/mono/blob/main/packages/niivue/FEATURE_PARITY.md)
tracks what has not been ported yet.
