Skip to content

nv-web-component

View as Markdown

@niivue/nv-web-component gives you two HTML tags, <niivue-viewer> and <niivue-scene>, that show NiiVue viewers on a page. Use it when you are not using a framework, or when you want to treat a viewer like any other page element: set its properties, call its methods and listen for its events.

The tags create the canvas, start NiiVue, resize the viewer when the element changes size and clean up when it is removed.

Install

Terminal window
npm install @niivue/nv-web-component@next @niivue/niivue@next

NiiVue is installed next to the tags rather than built into them, so build your page with a bundler such as Vite, which finds both for the browser.

Your first viewer

<niivue-viewer id="viewer" style="height: 500px"></niivue-viewer>
<script type="module">
import '@niivue/nv-web-component'
const viewer = document.querySelector('#viewer')
viewer.volumes = [{ url: '/volumes/mni152.nii.gz' }]
</script>

Importing the package is enough to make both tags work. The viewer fills the element, so give it a height.

Which tag do you need?

  • One viewer on a page: <niivue-viewer>. See One viewer.
  • Several viewers in a grid, optionally moving together: <niivue-scene>. See Several viewers.

Both tags hand you the NiiVue instance behind each viewer, so everything in the NiiVue guides still applies. If your app is written in React, the React package fits it better.

Using it from TypeScript

The package ships its types. Name the element type when you look the element up, and the type of an event’s detail when you read it:

import type { NiivueViewerElement, NVImage } from '@niivue/nv-web-component'
const viewer = document.querySelector<NiivueViewerElement>('#viewer')
viewer?.addEventListener('image-loaded', (event) => {
const volume = (event as CustomEvent<NVImage>).detail
console.log(volume.name)
})

The scene’s type is NiivueSceneElement.

When something does not work

  • The viewer does not show up. The element has no height. Give it one with CSS.
  • Changing volumes did nothing. Assign a new list. Changing the old list in place, for example with push, is not noticed.
  • A method such as setColormap did nothing. The image is not loaded yet. Wait for the image-loaded event, or put the setting in the volumes list instead.
  • options were ignored. The viewer reads them once, when it starts. Set them before the element goes on the page.
  • A viewer went blank after it was moved. Removing an element from the page shuts its viewers down for good, and moving it removes it first. Create a new element instead.
  • An image did not appear and nothing says why. Listen for the niivue-error event, which both tags send. On a viewer, event.detail is the error; on a scene, it is event.detail.error.