Tutorial

This is the guided, end-to-end path: start from nothing and finish with a working viewer that shows the full UniProt annotation for a protein plus your own track, recoloured to match your site. It’s one continuous example on a single protein: P05067, amyloid precursor protein, the reference accession used throughout these docs.

Each step ends with a Try it live link that opens the exact setup in the playground, so you can see it render and edit it without leaving the browser. When you want the full detail behind a step, follow the links to the how-to guides.

The quickest way to follow along is the Starter Kit: a no-build template repository you can copy and publish with GitHub Pages, or serve from your own computer with one command (its README has the steps for Windows, macOS and Linux). Opening its index.html by double-clicking doesn’t work: browsers block a page opened from disk from reading the config. You can also work in your own page served by any static file server or your app’s dev server, or use the playground for the config-only steps. No build tooling is required.

Note

The configuration surface below (rows:, kind:, extends:) is v5. The stable 4.x release does not understand it, so use the version Step 1 loads.

Step 1: Add the component and point it at an accession

<protvista-uniprot> is a web component: a custom element that works in any page with no bundler or framework. Load it once and drop the tag in with an accession:

Paste the following HTML snippet into the <body> of your HTML page. This snippet is not YAML or JSON, so do not paste it into the playground’s config editor. To try the viewer without editing an HTML file, use the “Try it live” link below.

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

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

That address serves the published v5 beta straight from npm, so there is nothing to install. Pin the exact version, as above: @beta and @5 would move under you as the beta develops.

To build it yourself instead, clone the repository and copy the contents of dist/ next to your page. Copy the whole folder, not just the one file: the build is split up, so protvista-uniprot.mjs loads errors.js and filter-config.js from the same place (and format.js / js-yaml.js when it needs them), and will not run on its own.

git clone --branch next https://github.com/ebi-webcomponents/protvista
cd protvista
pnpm install
pnpm build

Then copy the contents of dist/ next to your HTML page. The --branch next matters: the repository’s default branch, main, is the 4.x line.

Either way, the accession attribute on its own gives you the full default UniProt viewer for that protein: domains, variants, binding sites, structure coverage, AlphaFold confidence, and more. No config required.

Try it live

Open the default viewer for P05067. Swap the accession in the header to view any other protein.

The full default UniProt viewer, from one accession and no configuration.

Embed the viewer covers both ways to load the component and every attribute (config-src, notooltip, nostructure, …).

Step 2: Add your own track from a CSV

Now bring your own annotations. A features track can read a CSV file directly: point data: at the file and the .csv extension picks the parser for you: no adapter: needed.

Say your lab has flagged some hotspot regions. Put them in a CSV with the feature-record columns type,start,end,description,score:

type,start,end,description,score
DOMAIN,18,289,Extracellular domain (custom re-annotation),0.95
BINDING,132,140,Predicted heparin-binding site,0.87
REGION,290,340,Acidic-rich linker region,0.6
MUTAGEN,614,614,Lab-observed loss-of-function point mutation,0.75

Then describe a viewer that shows just that file as one standalone track (a rows: entry with data: and no tracks: needs no group wrapper):

accession: P05067
rows:
  - id: hotspots
    label: Hotspots
    kind: features
    data: ./hotspots.csv
    description: Hotspot regions identified by our lab's pipeline

Save the config as my-config.yaml next to hotspots.csv and point the element at it:

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

Caution

data: ./hotspots.csv is fetched relative to the hosting page, not the config file. If a file-backed track renders empty, this is the usual cause: serve the page from the same directory as the data, or use an absolute URL.

Try it live

Open the CSV track in the playground. It renders the same config against a hosted copy of hotspots.csv. Or open the playground, press Load data file… and pick your own CSV. It is read in your browser and never uploaded.

A standalone track loaded from a CSV file.

Load your own data covers the full feature record and the TSV, JSON, and BED formats. type drives the colour and shape you see above — Feature type and shape vocabulary lists every recognised value and what an unrecognised one like HOTSPOT would look like instead.

Step 3: Layer it onto the full UniProt viewer

A standalone track is a viewer of its own. More often you want your track on top of everything UniProt already provides. Instead of rebuilding the default viewer, extends it: you inherit all its sources, groups, and themes, and declare only your addition.

The custom data can be simpler here — the default viewer supplies the rest:

type,start,end,description,score
DOMAIN,18,289,Custom re-annotation of the extracellular domain,0.9
BINDING,614,614,Lab-observed candidate binding residue,0.72

accession: P05067
extends: /src/default-config.yaml

rows:
  - id: MY_LAB
    label: My lab
    tracks:
      - id: hotspots
        kind: features
        data: ./hotspots.csv
        description: Hotspot regions identified by our lab's pipeline, layered on top of the canonical UniProt viewer

That’s the whole config: the full canonical viewer, with a My lab group added at the end.

Caution

extends: /src/default-config.yaml resolves only when the page is served from this repo’s root; a deployed site must point extends at a hosted copy instead — either your own, or the published package on a CDN: https://cdn.jsdelivr.net/npm/protvista-uniprot@5.0.0-beta.5/dist/default-config.yaml. See Author a config for the merge rules and the full caveat.

Try it live

Open the full default viewer to see the base you’re extending, then open the extended viewer to see your own track layered on top of it — that preset uses the CDN extends: URL above, so it resolves right on the hosted page.

A lab’s own group layered on top of the canonical UniProt viewer with extends:.

Step 4: Style it

Finally, make it yours. There are two levers, no rebuild required.

No code: from the config. A theme: block recolours the viewer chrome directly, so an author who doesn’t write CSS can still brand the viewer. labelColor tints the row-label panel — group headers get the colour, track labels a lighter tint of it, so the group/track hierarchy stays visible; the optional accentColor sets focus rings and the datatable’s active-row marker. Dark or light, the label text, caret and hover state are derived from your colour, so a dark brand colour stays readable rather than leaving near-black text on a near-black cell. (One caveat: mid-greys around #808080 sit too close to both black and white for any text to reach full AA contrast — the viewer picks the better of the two, but a clearly light or dark colour is the safer choice.)

theme:
  labelColor: '#e8f5e9'
  accentColor: '#2e7d32'

Try it live

Open the inline-data preset, which carries a theme: block — edit the colours and press Run.

From your page’s CSS. For full control, <protvista-uniprot> exposes --protvista-* design tokens, and its datatable exposes ::part hooks — set them in ordinary CSS on the page:

protvista-uniprot {
  --protvista-color-accent: #7b2d8e;
  --protvista-group-label-bg: #efe6f5;
}

Caution

The two levers are not additive: a config theme: wins. labelColor and accentColor are applied as inline styles on the element, so they override page CSS targeting the same tokens — including both tokens in the example above. Pick one lever, or force the CSS with !important. See No-code theming from the config.

Theme the viewer lists every token and the datatable ::part hooks.

The inline-data preset’s theme: block: labelColor tints the row-label panel.

You’re done

You went from an empty page to a viewer that shows the full UniProt annotation for a protein, adds your own track from a CSV, and matches your site’s colours.

Where to go next:

• Author a config — every field a config can hold.
• Load your own data — TSV, JSON, BED, and inline data.
• Theme the viewer — the full token and ::part reference.
• Configuration vs data — what your config controls versus what a data provider supplies.
• Escape hatches — custom parsers, kinds, and themes when the built-ins aren’t enough.
• Playground — edit any config live and share it by link.
• Starter Kit — a no-build template repository to copy and go.
• Runnable examples — the CI-validated configs this tutorial draws from.

Licensed under CC BY 4.0.