Embed the viewer

ProtVista is a web component: a custom element, <protvista-uniprot>, that works in any web page or framework without extra setup. This page shows the two ways to load it and the handful of attributes you’ll use most.

The quickest possible viewer

Point the element at a UniProt accession and you get the full default UniProt viewer for that protein:

<script
  type="module"
  src="https://cdn.jsdelivr.net/npm/protvista-uniprot@5.0.0-beta.2/dist/protvista-uniprot.mjs"
></script>

<protvista-uniprot accession="P05067"></protvista-uniprot>

That’s it — no config required. P05067 is Amyloid precursor protein, the reference protein used throughout these docs; swap in any UniProt accession.

Two ways to load the component

1. As a module script in a static page

Import the built file as an ES module, then use the tag. The simplest source is a CDN, which serves the published v5 beta with nothing to install:

<script
  type="module"
  src="https://cdn.jsdelivr.net/npm/protvista-uniprot@5.0.0-beta.2/dist/protvista-uniprot.mjs"
></script>

<protvista-uniprot accession="P05067"></protvista-uniprot>

Pin the exact version, as above: @beta and @5 would move under you as the beta develops.

To host the file yourself instead, run yarn install && yarn build in a clone of the repository, copy the contents of dist/ next to your page, and point the tag at your own copy (src="./protvista-uniprot.mjs"). Copy the whole folder: the build is split up, so the .mjs loads sibling files from the same directory and will not run alone.

2. As an npm package

Install protvista-uniprot and import it once — the element self-registers as <protvista-uniprot> on import, so you don’t call customElements.define yourself:

import 'protvista-uniprot';

<protvista-uniprot accession="P05067"></protvista-uniprot>

Caution

A plain npm install protvista-uniprot gives you 4.9.3 — the current stable release, which predates the config surface these docs describe (rows:, kind:, extends:) and will not read the configs in this guide. That stays true for as long as v5 is in beta, because the beta publishes under the beta dist-tag rather than latest. Install the beta explicitly with npm install protvista-uniprot@beta, or build from source as above.

Either way, the tag behaves like any other HTML element — style it, size it, and place it wherever you like.

The attributes you’ll use

Set these as HTML attributes (or as JavaScript properties on the element).

Attribute	Type	What it does
accession	string	The UniProt accession to display. Takes precedence over an accession in a config.
config-src	string	URL or path to a YAML or JSON config, fetched at mount time. See Author a config.
viewerConfig	object	A config object (or a YAML/JSON string) assigned as a JS property — there is no matching HTML attribute. An alternative to config-src when you already have the config in memory.
nostructure	boolean	Hides the 3D structure group.
notooltip	boolean	Suppresses the built-in click tooltip (set this when you render your own — see Rich tooltips in React).
suspend	boolean	Pauses rendering, e.g. while an accession is about to change.

Driving it with your own config

Once you want more than the default UniProt view — your own tracks, your own data, a different arrangement — point config-src at a config file:

<protvista-uniprot config-src="./my-config.yaml"></protvista-uniprot>

my-config.yaml

accession: P05067
sources:
  features: https://www.ebi.ac.uk/proteins/api/features/{accession}
rows:
  - id: DOMAINS
    tracks:
      - id: domain
        kind: features
        filter: DOMAIN
        data: features

This renders a single collapsible group with one track of domain features. Read Author a config next to understand each part, or open the playground to edit a config live and watch it render.

Browser support

ProtVista needs a modern browser with support for ES2021 and Web Components (Custom Elements v1): Chrome/Edge 92+, Firefox 90+, Safari 15+.

Next steps

• Author a config — the structure of a config document.
• Built-in track kinds — what each kind draws.
• Load your own data — bring a CSV/TSV/JSON/BED file.

Licensed under CC BY 4.0.