Web Components

BGC Viewer provides web components that can be easily integrated into any web application, regardless of framework.

Installation

Via npm

npm install @medemagroup/bgc-viewer-components

Via CDN

<script type="module" src="https://unpkg.com/@medemagroup/bgc-viewer-components@latest/dist/web-components/bgc-viewer-components.es.js"></script>

Available Components

Custom Elements (Web Components)

<bgc-region-viewer-container>

Container component with automatic data loading. This is the simplest way to display a BGC record.

Features:

• Automatic data fetching from a DataProvider
• Built-in loading states and error handling
• Only requires dataProvider and recordId props
• Manages all data lifecycle (fetching regions, features, PFAM colors, etc.)

Best for:

• Simple integrations where you just want to display a record by ID
• Quick demos and prototypes
• When using standard data providers (JSONFileProvider or BGCViewerAPIProvider)

Usage:

<bgc-region-viewer-container 
  record-id="NC_003888.3"
  width="1000"
  height="500">
</bgc-region-viewer-container>

<script type="module">
  import { JSONFileProvider } from '@medemagroup/bgc-viewer-components';

  const provider = new JSONFileProvider();
  await provider.loadFromFile('/data/bgc.json');

  const container = document.querySelector('bgc-region-viewer-container');
  // Complex objects must be set via JavaScript properties
  container.dataProvider = provider;
</script>

Note: Simple values (strings, numbers, booleans) can be set as HTML attributes. Complex objects like dataProvider must be set via JavaScript properties.

<bgc-region-viewer>

Core visualization component for displaying biosynthetic gene clusters.

Features:

• Region selector dropdown for switching between BGC regions
• Multi-select track dropdown for showing/hiding feature layers
• Interactive feature details panel (click features to see info)
• Full control over what data is displayed and when

Best for:

• When you have pre-loaded data or custom data sources
• Complex applications with state management
• Custom data loading logic or transformations
• Fine-grained control over rendering and updates

Usage:

<bgc-region-viewer
  width="800"
  height="400"
  show-domains="true">
</bgc-region-viewer>

<script type="module">
  // RegionViewer requires pre-loaded data passed as props
  const viewer = document.querySelector('bgc-region-viewer');
  viewer.recordInfo = { recordId: 'NC_003888.3', filename: 'bgc.json' };
  viewer.regions = [/* array of regions */];
  viewer.features = [/* array of features */];
  viewer.pfamColorMap = {/* domain colors */};
</script>

Choosing Between Components

Aspect	RegionViewerContainer	RegionViewer
Setup Complexity	Simple (2 props)	More complex (many props)
Data Loading	Automatic	Manual
Flexibility	Limited	High
Use Case	Quick display by ID	Custom data flows
Best For	Demos, simple apps	Complex apps, custom logic

Exported Classes

The package also exports JavaScript classes for programmatic use:

BGCViewerAPIProvider

Data provider class for fetching data from the BGC Viewer REST API.

import { BGCViewerAPIProvider } from '@medemagroup/bgc-viewer-components';

const provider = new BGCViewerAPIProvider('http://localhost:8000');
const data = await provider.fetchRegion('NC_003888');

JSONFileProvider

Data provider class for loading data from JSON files.

import { JSONFileProvider } from '@medemagroup/bgc-viewer-components';

const provider = new JSONFileProvider();
const data = await provider.loadFromFile('/data/bgc.json');

TrackViewer

Low-level track viewer class for direct canvas-based rendering.

import { TrackViewer } from '@medemagroup/bgc-viewer-components';

const viewer = new TrackViewer({
  container: '#viewer',
  width: 800,
  height: 400
});
viewer.render(data);

TypeScript Types

The following TypeScript types are exported for type-safe development:

• TrackViewerConfig - Configuration options for TrackViewer
• TrackData - Track data structure
• AnnotationData - Annotation data structure
• AnnotationType - Annotation type enum
• TrackViewerData - Complete viewer data structure
• DrawingPrimitive - Drawing primitive interface
• DrawingPrimitiveType - Drawing primitive type enum

Usage Examples

Plain HTML

<!DOCTYPE html>
<html>
<head>
  <title>BGC Viewer Example</title>
  <script type="module" src="https://unpkg.com/@medemagroup/bgc-viewer-components@latest/dist/web-components/bgc-viewer-components.es.js"></script>
</head>
<body>
  <h1>My BGC Visualization</h1>
  
  <bgc-region-viewer-container id="viewer" width="1000" height="500">
  </bgc-region-viewer-container>

  <script type="module">
    import { JSONFileProvider } from 'https://unpkg.com/@medemagroup/bgc-viewer-components@latest/dist/web-components/bgc-viewer-components.es.js';

    const provider = new JSONFileProvider();
    await provider.loadFromFile('/data/my-bgc.json');

    const viewer = document.getElementById('viewer');
    viewer.dataProvider = provider;
    viewer.setAttribute('record-id', 'NC_003888.3'); // record ID from your JSON file

    viewer.addEventListener('annotation-clicked', (event) => {
      console.log('Annotation clicked:', event.detail);
    });
  </script>
</body>
</html>

React

import { useEffect, useRef } from 'react';
import { JSONFileProvider } from '@medemagroup/bgc-viewer-components';

function BgcView() {
  const viewerRef = useRef(null);

  useEffect(() => {
    const viewer = viewerRef.current;
    const provider = new JSONFileProvider();
    provider.loadFromFile('/data/my-bgc.json').then(() => {
      viewer.dataProvider = provider;
      viewer.setAttribute('record-id', 'NC_003888.3'); // record ID from your JSON file
    });

    // Custom events must be bound imperatively in React
    const handleAnnotationClicked = (event) => {
      console.log('Annotation clicked:', event.detail);
    };
    viewer.addEventListener('annotation-clicked', handleAnnotationClicked);
    return () => viewer.removeEventListener('annotation-clicked', handleAnnotationClicked);
  }, []);

  return (
    <bgc-region-viewer-container
      ref={viewerRef}
      width="800"
      height="400"
    />
  );
}

Vue

<template>
  <bgc-region-viewer-container
    ref="viewer"
    :width="800"
    :height="400"
    @annotation-clicked="handleAnnotationClicked"
  />
</template>

<script setup>
import { ref, onMounted } from 'vue';
import { JSONFileProvider } from '@medemagroup/bgc-viewer-components';

const viewer = ref(null);

onMounted(async () => {
  const provider = new JSONFileProvider();
  await provider.loadFromFile('/data/my-bgc.json');
  viewer.value.dataProvider = provider;
  viewer.value.setAttribute('record-id', 'NC_003888.3'); // record ID from your JSON file
});

const handleAnnotationClicked = (event) => {
  console.log('Annotation clicked:', event.detail);
};
</script>

Angular

import { Component, ViewChild, ElementRef, AfterViewInit, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
import { JSONFileProvider } from '@medemagroup/bgc-viewer-components';

@Component({
  selector: 'app-bgc-view',
  template: `
    <bgc-region-viewer-container
      #viewer
      [attr.width]="800"
      [attr.height]="400"
      (annotation-clicked)="handleAnnotationClicked($event)">
    </bgc-region-viewer-container>
  `,
  schemas: [CUSTOM_ELEMENTS_SCHEMA]
})
export class BgcViewComponent implements AfterViewInit {
  @ViewChild('viewer') viewer!: ElementRef;

  ngAfterViewInit() {
    const provider = new JSONFileProvider();
    provider.loadFromFile('/data/my-bgc.json').then(() => {
      this.viewer.nativeElement.dataProvider = provider;
      this.viewer.nativeElement.setAttribute('record-id', 'NC_003888.3'); // record ID from your JSON file
    });
  }

  handleAnnotationClicked(event: CustomEvent) {
    console.log('Annotation clicked:', event.detail);
  }
}

Styling

Web components can be styled using CSS custom properties:

bgc-region-viewer {
  --gene-stroke: #333;
  --gene-fill: #4a90e2;
  --domain-stroke: #666;
  --domain-fill: #f39c12;
  --background: #ffffff;
  --text-color: #333;
  --font-family: 'Arial', sans-serif;
}

API

Properties

Simple values (strings, numbers) can be set as HTML attributes using kebab-case. Complex objects and arrays must be set as JavaScript properties using camelCase.

<bgc-region-viewer-container> properties:

Property / Attribute	Type	Description
record-id / recordId	string	Record ID to load
initial-region-id / initialRegionId	string	Region to pre-select on load (optional)
dataProvider	JS property	DataProvider instance (required)
recordData	JS property	Full record metadata { entryId, recordId, filename } (optional)

<bgc-region-viewer> properties:

Property / Attribute	Type	Description
selected-region-id / selectedRegionId	string	Currently selected region (optional)
recordInfo	JS property	Record metadata { recordId, filename, recordInfo: { description } }
regions	JS property	Array of region objects [{ id, region_number, product }]
features	JS property	Array of genomic features [{ type, location, qualifiers }]
regionBoundaries	JS property	Region boundaries { start, end } (optional)
pfamColorMap	JS property	PFAM domain color map { 'PF00001': '#FF0000', ... } (optional)

Methods

<bgc-region-viewer> exposes two methods via its element reference:

const viewer = document.querySelector('bgc-region-viewer');

// Clear all loaded data and reset the viewer to an empty state
viewer.clearViewer();

// Rebuild/re-render the viewer with the current data
viewer.rebuildViewer();

<bgc-region-viewer-container> does not expose any public methods.

Events

Both components dispatch custom events. Listen to them with addEventListener:

const viewer = document.querySelector('bgc-region-viewer-container');

// Fired when the user selects a different region
viewer.addEventListener('region-changed', (event) => {
  console.log('Region:', event.detail);
});

// Fired when the user clicks an annotation/feature
viewer.addEventListener('annotation-clicked', (event) => {
  console.log('Annotation:', event.detail);
});

// Fired when an error occurs during data loading
viewer.addEventListener('error', (event) => {
  console.error('Error:', event.detail);
});

<bgc-region-viewer> additionally emits annotation-hovered when the user hovers over an annotation.

See Also

• Track Viewer Component
• Interactive Examples