> For the complete documentation index, see [llms.txt](https://docs.labii.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.labii.com/widgets/section-widgets/biology/genome-browser/igv-genome-browser.md). # IGV Genome Browser ## Specs | Label | Value | | ------------------------- | ----------------------------- | | **Version** | 0.1.1 (updated on 2026-05-31) | | **Developer** | Labii Inc. | | **Type** | Section | | **Support Configuration** | Yes | ## Overview The IGV Genome Browser widget embeds [igv.js](https://igv.org/doc/igvjs/), an interactive genome visualization component developed by the Integrative Genomics Viewer team, directly inside a Labii record section. It lets laboratory teams open a reference genome, jump to a locus, load one or more genomic tracks, and overlay regions of interest without leaving the current record. This is useful for reviewing alignments, annotations, variants, or custom genomic intervals alongside experiment notes, sample metadata, and other Labii content. The widget configuration follows the core IGV.js browser creation model, especially the official browser creation, reference genome, and ROI documentation. ## Use Cases * **NGS result review**: Display BAM, CRAM, BigWig, BED, or variant tracks next to sequencing run records for fast visual inspection. * **Targeted assay validation**: Open a known locus and overlay regions of interest to confirm coverage or variant evidence for specific amplicons or genes. * **Reference-specific projects**: Load a custom FASTA or twoBit reference for non-model organisms, proprietary assemblies, or project-specific contigs. * **Annotation comparison**: Combine gene models, coverage tracks, and variant tracks in one browser to compare evidence across track types. * **Collaborative record review**: Store a reproducible browser setup in a section so team members open the same initial genome, locus, and track layout. * **Quality and compliance workflows**: Keep genome visual evidence attached to the record where interpretations, approvals, and downstream decisions are documented. ## Interface ### Read-only View The read-only view displays an embedded IGV.js browser inside the section. Labii keeps the core IGV browsing experience, while exposing several menu actions that are especially useful in record-centric workflows: * **Genome menu**: Select the active genome or reference context configured for the widget. * **Tracks menu**: Manage visible tracks with Labii-specific bulk actions, including showing or hiding selected tracks, selecting all tracks, and unselecting all tracks. * **Sample Info menu**: Open sample metadata associated with the loaded browser session when available in the current workflow. * **Session menu**: Work with the current browser session state. * **Save Image menu**: Export the current browser view from the dropdown menu. * **Locus navigation**: The initial locus is loaded automatically, and navigation controls can expose search, zoom-in, and zoom-out actions. * **Track display**: Tracks defined in **Tracks JSON** are rendered in stacked lanes with IGV.js-specific controls for inspection and interaction. * **Ideogram and ruler**: Optional ideogram and genomic ruler elements provide chromosome context and genomic coordinates. * **Visual guides**: Optional center and cursor guides help users align attention to a precise coordinate while inspecting dense genomic data. * **ROI overlays**: Regions of interest appear as translucent overlays across tracks when configured. The section is primarily a viewer. Most user interaction happens through pan, zoom, search, session control, and track inspection rather than by editing record text. ### Edit View In edit mode, the widget remains an interactive genome browser, but the main changes are typically made through the section configuration rather than inline content entry. Users can continue to inspect loci and tracks while editing the record, then adjust genome, track, ROI, storage, or interface settings through the widget configuration panel when needed. Labii also extends default IGV track interaction in this view. Standard IGV behavior typically allows users to drag tracks one by one to reorder them. In the Labii IGV widget, users can select multiple tracks and drag the full selection together, which makes reorganizing larger track sets faster.
{% hint style="info" %} The IGV Genome Browser widget is most effective when remote genomic files are hosted on web servers that support CORS and byte-range requests, which are commonly required for indexed genomic formats. {% endhint %} ## Configuration The IGV Genome Browser widget maps directly to standard IGV.js browser configuration concepts. In IGV.js, one of either a genome identifier or a reference object is required. In Labii, this means you should configure **Genome** or **Reference JSON** before expecting the browser to load meaningful data. {% stepper %} {% step %} Add the section to a record and choose **IGV Genome Browser** from the widget library. {% endstep %} {% step %} Configure the genomic context: * **Genome**: Enter a supported IGV genome identifier such as `hg38`, `hg19`, or another hosted/GenArk assembly ID. * **Reference JSON**: Use this instead of Genome when you need a custom reference definition with your own FASTA or twoBit URLs. {% endstep %} {% step %} Set the initial view and data sources: * **Locus**: Define the initial genomic position, for example `chr17:7,572,927-7,579,912`. * **Tracks JSON**: Provide a JSON array of IGV.js track configuration objects to load on startup. * **Regions Of Interest JSON**: Optionally provide ROI definitions to highlight intervals across tracks. {% endstep %} {% step %} Adjust browser behavior and appearance: * **Track Defaults JSON**: Provide default settings for supported track types. * **Browser folder**: Optionally set a local folder path for storing files added from the browser. * **Minimum Bases**: Set the minimum zoom window size in base pairs. * **Height**: Set the viewer height in pixels. * **Show navigation**, **Show ideogram**, **Show ruler**, **Show SVG button**, **Show center guide**, **Show cursor track guide**: Toggle interface elements on or off. * **Query parameters supported**: Enable IGV.js query-parameter initialization behavior when your deployment uses shared URLs or external launch parameters. {% endstep %} {% step %} Save the section and verify that the browser loads the expected genome, locus, and tracks. {% endstep %} {% endstepper %} ### Required Settings * **Genome**: A genome identifier understood by IGV.js. Use this when a built-in IGV-hosted genome or UCSC GenArk assembly is sufficient. * **Reference JSON**: A custom reference object. Use this when you need explicit control over FASTA or twoBit files, indexes, cytobands, aliases, or reference-linked tracks. {% hint style="info" %} Configure at least one of **Genome** or **Reference JSON**. In practice, use **Genome** for standard assemblies and **Reference JSON** for custom genomes or when you need full control over reference assets. {% endhint %} ### Optional Settings * **Locus**: The initial genomic location. This is typically a string such as `chr1:1-1000` and determines what users see first. * **Tracks JSON**: An array of IGV.js track objects loaded when the widget opens. Use this to preload alignments, annotations, variants, coverage, and other supported tracks. * **Reference JSON**: Optional when **Genome** is already set, but preferred whenever you need custom reference metadata or URLs. * **Track Defaults JSON**: A JSON object that defines default display properties for track types, helping you keep a consistent look across multiple tracks. * **Browser folder**: Maps to the `local_folder_path` configuration. Use this when you want files added from the widget copied to a specific local browser folder instead of being uploaded into the Labii file system. * **Regions Of Interest JSON**: An array of ROI configuration objects. ROI sets can be supplied from annotation files such as BED/GFF or from explicit `{chr, start, end}` feature arrays. * **Minimum Bases**: Minimum window size in base pairs when zooming in. IGV.js defaults this to 40, and increasing it prevents overly deep zoom states. * **Height**: The height of the embedded browser viewport in pixels. * **Show navigation**: Displays basic navigation controls such as search and zoom. * **Show ideogram**: Displays the chromosome ideogram in the browser header. * **Show ruler**: Displays the genomic ruler track. * **Show SVG button**: Displays a control for exporting the current browser view as SVG. * **Show center guide**: Displays center marker lines that frame the position at the center of the current view. * **Show cursor track guide**: Displays a vertical guide line that follows the pointer across tracks. * **Query parameters supported**: Enables IGV.js initialization using supported query parameters when applicable in your hosting context. ### Advanced Configuration The examples below mirror the structures documented in the official IGV.js guides. #### Local Browser Folder Configuration Use the following configuration entry to control how newly added files are stored: ```javascript local_folder_path: { title: "Browser folder", description: "Select a browser folder for local IGV file storage. If empty, dropped files are uploaded to Labii." } ``` The configuration label above matches the widget setting text. In current Labii usage, end users do not drag and drop files directly into the browser canvas; the setting controls where newly added track files are stored when they are added through the supported workflow. Storage behavior depends on whether this value is set: * If `local_folder_path` is not provided, files added through the widget are uploaded to S3 through the Labii file system. * If `local_folder_path` is provided, added files are copied to that local folder path instead of being uploaded. * A local browser folder is generally better for very large sequence files because it avoids routing those files through Labii-managed object storage. #### Example Reference JSON ```json { "id": "custom-hg38", "name": "Human GRCh38 Custom", "fastaURL": "https://example.org/genomes/hg38.fa", "indexURL": "https://example.org/genomes/hg38.fa.fai", "cytobandURL": "https://example.org/genomes/cytoBandIdeo.txt" } ``` #### Example Tracks JSON ```json [ { "name": "RefSeq Genes", "type": "annotation", "format": "bed", "url": "https://example.org/tracks/refseq.bed.gz", "indexURL": "https://example.org/tracks/refseq.bed.gz.tbi" } ] ``` #### Example Regions Of Interest JSON ```json [ { "name": "Clinically relevant regions", "url": "https://example.org/tracks/roi.bed", "indexed": false, "color": "rgba(255, 0, 0, 0.20)" } ] ``` {% hint style="warning" %} For large BAM, CRAM, VCF, FASTA, and other indexed genomic assets, verify that the source server supports range requests and cross-origin access before troubleshooting the widget itself. {% endhint %} ## Additional Functions ### Locus Navigation and Search When **Show navigation** is enabled, users can move rapidly between genomic regions with the built-in search and zoom controls provided by IGV.js. This is useful for jumping from one gene or coordinate range to another during record review. ### Track Loading and Rendering The widget can open multiple track types defined in **Tracks JSON**, allowing one section to combine annotations, alignments, variants, coverage, and other genomic evidence. **Track Defaults JSON** helps standardize how supported track types render when the page loads. In the **Tracks** dropdown, users can: * Show or hide selected tracks. * Select tracks before applying a bulk action. * Select all tracks. * Unselect all tracks. Labii also extends default IGV behavior by allowing all selected tracks to be dragged together. This is useful when reorganizing many visible tracks as a group instead of moving them one at a time. Users cannot add new tracks by dragging and dropping files directly into the browser canvas. New files must be added through the widget's supported add-track workflow, after which they are stored according to the `local_folder_path` setting. ### Regions Of Interest Overlay ROI sets defined in **Regions Of Interest JSON** overlay translucent highlight regions across tracks. This is useful for emphasizing primers, amplicons, exon intervals, pathogenic loci, or other regions that matter to the current workflow. ### SVG Export If **Show SVG button** is enabled, users can export the current browser view as an SVG image. {% stepper %} {% step %} Open the record and navigate to the genomic region you want to capture. {% endstep %} {% step %} Adjust the visible tracks, zoom level, and highlighted intervals until the browser shows the desired view. {% endstep %} {% step %} Click the **SVG** export button in the widget header or browser controls. {% endstep %} {% step %} Save the exported image for reports, review packages, or downstream documentation. {% endstep %} {% endstepper %} ### Shared and Parameterized Views When **Query parameters supported** is enabled in a compatible deployment, the widget can participate in IGV.js query-parameter based initialization. This can support externally launched views or shared links that open directly to a specific genomic context. For full option details, refer to the official IGV.js documentation: * [IGV.js overview](https://igv.org/doc/igvjs/) * [Browser creation](https://igv.org/doc/igvjs/#Browser-Creation/) * [Reference genome](https://igv.org/doc/igvjs/#Reference-Genome/) * [Regions of interest](https://igv.org/doc/igvjs/#Regions-of-Interest/) ## Best Practices ### Data Preparation * Use indexed genomic file formats whenever possible so users can navigate large datasets efficiently. * Keep reference definitions stable across related records so teams compare tracks against the same assembly. * Name tracks clearly in **Tracks JSON** so users can distinguish annotation, alignment, coverage, and variant evidence at a glance. ### Performance Optimization * Start the widget at a focused **Locus** instead of a very broad genomic span when loading heavy tracks. * Use **Minimum Bases** to prevent users from zooming into impractically small windows for the underlying data type. * Set **Height** high enough for readability but avoid oversized viewers on pages with many other sections. * Prefer **Browser folder** (`local_folder_path`) for large local sequence assets when you want to avoid uploading them into S3-backed Labii storage. ### Deployment and Access * Host genomic assets on servers that support CORS and byte-range requests. * Validate external URLs in **Reference JSON**, **Tracks JSON**, and **Regions Of Interest JSON** before rolling the widget into production templates. * Use built-in genome IDs through **Genome** when possible to reduce configuration overhead and risk. {% hint style="success" %} For reproducible record review, store a fixed initial genome, locus, and standard track set in the widget configuration so every user starts from the same genomic context. {% endhint %} ### Common Pitfalls To Avoid * **Avoid** configuring both a vague broad locus and many heavy remote tracks at once, which can slow the first load significantly. * **Avoid** using unindexed FASTA or large annotation files for production-scale browsing unless the files are intentionally small. * **Avoid** assuming a remote data source is accessible just because the URL opens in a browser tab; indexed genomic browsing often depends on additional server behavior. * **Avoid** expecting desktop-style drag-and-drop file import into the browser canvas; this widget does not support dropping files to create new tracks. * **Instead**, test the widget with the exact production URLs and expected user permissions before publishing a template broadly. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.labii.com/widgets/section-widgets/biology/genome-browser/igv-genome-browser.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.