nv-web-component
@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
npm install @niivue/nv-web-component@next @niivue/niivue@nextpnpm add @niivue/nv-web-component@next @niivue/niivue@nextyarn add @niivue/nv-web-component@next @niivue/niivue@nextbun add @niivue/nv-web-component@next @niivue/niivue@nextNiiVue 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
volumesdid nothing. Assign a new list. Changing the old list in place, for example withpush, is not noticed. - A method such as
setColormapdid nothing. The image is not loaded yet. Wait for theimage-loadedevent, or put the setting in thevolumeslist instead. optionswere 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-errorevent, which both tags send. On a viewer,event.detailis the error; on a scene, it isevent.detail.error.