TranscriptBrowserRenderer v1.0.60¶
The framework-agnostic core renderer. Extends the internal base class BaseRenderer. All domain logic (navigation, mode switching, Channel add/remove, event callbacks) is exposed through this class's instance methods. React is bundled internally, so callers do not need to install React.
Each instance also exposes a set of internal Managers as read-only properties; see Internal Managers at the bottom of this page.
Constructor¶
| Parameter | Type | Required | Description |
|---|---|---|---|
config |
ITRConfig |
✓ | The complete configuration object. ITRConfig is a @deprecated alias of IRBrowerConfig; the two are equivalent. At minimum it must contain renderer (including containerId), locus, and channels. |
After construction the renderer is not yet mounted; you must call mount() manually.
import { TranscriptBrowserRenderer, defaultConfig } from "@rbrowser/main";
const renderer = new TranscriptBrowserRenderer({
...defaultConfig,
renderer: { ...defaultConfig.renderer, containerId: "root" },
});
renderer.mount(); // actually start rendering
Lifecycle¶
mount¶
method
Mounts the renderer into the DOM container identified by config.renderer.containerId. This method will:
- Create the WebGL context + main canvas
- Compute the initial Channel layout
- Install the
ResizeObserver, interaction events, and the Tooltip / Cursor / Highlight overlays - Start the render loop
- Trigger the first navigation based on
config.locus.mode(DNA / RNA / CDS)
destroy¶
method
Destroys the renderer and releases all resources: stops the render loop, removes event listeners, removes the DOM, and destroys all ChannelViews. After this call, isDestroyed returns true.
isDestroyed¶
getter
A read-only flag indicating whether the renderer has been destroyed. Third-party code in async callbacks should check this before accessing the renderer.
forceRedraw¶
method
Marks the renderer as dirty, forcing a redraw on the next animation frame. Only needed after modifying highlightManager externally — most internal state changes already trigger a redraw automatically.
Region navigation¶
navigateTo¶
method
Navigates directly to the given DNA interval using genomic coordinates. This updates both the loaded region and the viewport and triggers a data refetch. The chromosome name is automatically prefixed with chr (if missing).
| Parameter | Type | Required | Description |
|---|---|---|---|
chr |
string |
✓ | Chromosome name, e.g. "chr17" or "17". |
start |
number |
✓ | Start coordinate (inclusive), bp. |
end |
number |
✓ | End coordinate (exclusive), bp. |
region (setter)¶
setter
Navigates via a region string. This is the most commonly used navigation entry point in RBrowser — a single string covers three coordinate systems:
| Format | Example | Behavior |
|---|---|---|
chr:start-end |
"chr17:7571720-7590868" |
Goes directly through DNA navigation |
NAME:up:down |
"NANOG-204:5000:5000" |
RNA mode, taking the specified bp upstream and downstream |
NAME:flank |
"NANOG-204:5000" |
RNA mode, symmetric flank (5000 bp upstream and downstream) |
| With thousands separators | "chr17:7,571,720-7,590,868" |
Commas are stripped before parsing |
Throws when the format cannot be recognized.
Parsing in RNA mode
In NAME:up:down, the two numbers are upstream and downstream respectively — they are automatically corrected for strand orientation. If the browser has not yet loaded that transcript, it asynchronously queries the reference catalog before navigating.
// DNA mode
renderer.region = "chr17:7571720-7590868";
// RNA mode
renderer.region = "NANOG-204:5000:5000";
renderer.region = "VAMP3-201:2000";
region (getter)¶
getter
Returns the currently loaded region, always as a UCSC-style genomic coordinate string (e.g. "chr17:7571720-7590868"), even when the browser is in RNA / CDS mode. "Loaded" refers to the result of the last explicit navigation and does not change with pan/zoom.
viewRegion¶
getter
Returns the genomic coordinate string of the current visible window. Unlike region, viewRegion updates live with every pan/zoom frame, making it suitable for status-bar / URL synchronization.
viewRnaRegion¶
getter
When in RNA / CDS mode, returns the transcript-notation string of the current visible window (TRANSCRIPT-NAME:up:down). Returns an empty string in DNA mode.
renderer.region = "NANOG-204:5000:5000";
// After the user drags a bit:
renderer.viewRnaRegion; // "NANOG-204:4321:5212"
renderer.viewRegion; // "chr12:7785999-7795532"
getChromSize¶
method
Queries the length (bp) of a chromosome from the loaded chromsizes. Returns undefined when chromsizes are not loaded. Tolerant of chr-prefix differences.
Transcript async navigation¶
The following methods are all asynchronous: they query the reference catalog (REST API or SQLite-over-HTTP) for the transcript structure, then switch to RNA / CDS mode.
navigateByTranscript¶
method
Navigates by transcript name with a symmetric flank. After loading the transcript structure it enters RNA mode and switches the X axis to TSS-relative coordinates.
| Parameter | Type | Required | Description |
|---|---|---|---|
transcriptName |
string |
✓ | Transcript name, e.g. "NANOG-204". |
flank |
number |
✓ | How many bp to take upstream and downstream. |
navigateByTranscriptCDS¶
method
Navigates by transcript name and enters CDS mode directly (with introns collapsed).
navigateByTranscriptAnnotation¶
method
transcriptName: string,
dna: { chrom: string; start: number; end: number },
upstream?: number,
downstream?: number,
): Promise<void>
Used when the reference has a GFF annotation but no searchable transcript catalog. The given dna window is used to locate the transcript structure within the GFF, then switches to RNA mode. upstream / downstream default to 5000 each.
resolveTranscriptDNA¶
method
Resolves a transcript name to a DNA coordinate string ("chrN:start-end", with the flank applied) but does not switch to RNA mode. Returns null on failure. Suitable for the "I just want the coordinates without changing the view mode" scenario.
const region = await renderer.resolveTranscriptDNA("NANOG-204", 5000);
if (region) renderer.navigateTo(...region.match(/(\w+):(\d+)-(\d+)/)!.slice(1));
Viewport / Domain¶
getViewDomain¶
method
Returns the current visible domain: { start: number, end: number }. The coordinate system matches the current mode (DNA → genomic, CDS → cds-space).
setViewDomain¶
method
Programmatically sets the visible domain (pan/zoom). Does not trigger a data refetch — if you need to reload data, use navigateTo().
browserWidth¶
getter
The visible width of the main canvas (CSS pixels).
RNA mode¶
isRnaMode¶
getter
Whether the browser is currently in RNA mode (X axis in TSS-relative coordinates).
rnaInfo¶
getter
tssPos: number;
strand: "+" | "-";
chr: string;
name: string;
txStart: number;
txEnd: number;
} | null
Returns the transcript info for the current RNA mode. Returns null when not in RNA mode.
enableRnaMode¶
method
tssPos: number;
strand: "+" | "-";
chr: string;
name: string;
txStart: number;
txEnd: number;
}): void
Explicitly enables RNA mode with the provided transcript info. Usually does not need to be called directly — navigateByTranscript*() handles it automatically.
disableRnaMode¶
method
Switches back to DNA mode (genomic coordinate axis).
CDS mode¶
isCdsMode¶
getter
cdsInfo¶
getter
cdsMapper¶
getter
CDSCoordinateMapper exposes the genomicToCDS(pos) / cdsToGenomic(pos) / totalCDSLength interface, which can be used to map genomic coordinates into CDS space.
enableCdsMode¶
method
strand: "+" | "-";
chr: string;
name: string;
tssPos: number;
txStart: number;
txEnd: number;
}): void
disableCdsMode¶
method
panCdsView¶
method
Pans the CDS view by the given fraction of the current visible span (frac = 0.5 means scrolling right by half a screen). No-op when not in CDS mode.
zoomCdsView¶
method
Zooms the CDS view by a factor (>1 zooms in, <1 zooms out). No-op when not in CDS mode.
Data loading¶
loadData¶
method
Forces all Channels to refetch data for the current region. The status transitions from Loading to Loaded. Usually does not need to be called manually — navigateTo() and similar methods trigger it automatically.
Region list export¶
getRegionList¶
method
DNA: Array<DnaEntry>;
mRNA: Array<TranscriptEntry>;
RNA: Array<TranscriptEntry>;
CDS: Array<TranscriptEntry>;
}
Projects all current highlight intervals into all four coordinate systems at once and returns them. Regardless of the current view mode, all four arrays are always complete. Commonly used for: exporting to a paper, batch-feeding downstream analysis, or saving as BED.
Return structure
type DnaEntry = {
chr: string;
start: number; // genomic, bp
end: number;
strand: string; // "+" / "-" / "." (unknown)
assembly?: IAssemblyInfo; // the currently active reference genome
};
type TranscriptEntry = {
chr: string;
start: number; // coordinate system depends on the array semantics (see below)
end: number;
strand: string;
trans_id: string; // Ensembl transcript ID
trans_name: string; // e.g. "NANOG-204"
gene_id: string; // Ensembl gene ID
gene_name: string; // e.g. "NANOG"
tss: number; // TSS coordinate in genomic space
assembly?: IAssemblyInfo;
};
Coordinate systems of the four arrays
| Array | Coordinate system |
|---|---|
DNA |
Genomic coordinates, always available |
mRNA |
Mature mRNA space (exon coordinates after introns are collapsed), requires an exon mapper |
RNA |
Pre-mRNA space, offset relative to the TSS; negative values denote upstream of the TSS |
CDS |
CDS space (after introns + UTRs are collapsed) |
Each entry in all four arrays carries an optional assembly?: IAssemblyInfo. When no reference is available the assembly field is omitted; when there is no transcript context, the transcript fields of mRNA / RNA / CDS are filled with empty-string placeholders.
Example
import { historyManager } from "@rbrowser/main";
renderer.highlightManager.setRegion("region1", 7575000, 7580000, "#3867d6");
const regions = renderer.getRegionList();
regions.DNA.forEach(r => {
// r.assembly?.name === "GRCh38"
console.log(`${r.chr}:${r.start}-${r.end} @ ${r.assembly?.name}`);
});
// To write the current locus into history: use locusManager to get the full ILocus (add() only accepts ILocus)
historyManager.add(renderer.locusManager.getLocus());
Behavior change in v1.0.48
Starting with this version, every entry in all four arrays gains an assembly?: IAssemblyInfo field. Earlier versions returned only coordinates + transcript info, lacking the reference context. The new field is optional, so old code will not fail to compile.
Config / image export¶
exportConfig¶
method
Serializes the renderer's current active state into an ITRConfig: including the current channel order, visibility, visible domain, grid settings, live transcript offsets, and so on. The result can be fed directly into new TranscriptBrowserRenderer(config) to reproduce the current view.
exportBrowser¶
method
Exports the entire browser (including the axis, all channels, and legends) as an image or document and triggers a browser download.
format |
Implementation |
|---|---|
"PNG" |
canvas → blob → download |
"SVG" |
Each channel composed into a standalone SVG document (4× scale with vector text overlay) |
"PDF" |
Multi-page PDF (axis at the top of each page) |
Reference genome¶
applyReference¶
method
After switching the reference, reloads the chromsizes / cytoband / annotations, and updates the interaction bounds and axis nav bar. Usually called internally after ReferenceManager.switchTo(). See Type definitions for the full IReferenceConfig definition.
Event callbacks¶
The following callback-style APIs differ from the on() style of the Managers — only one callback is allowed, and re-registering overrides the previous one. Except for setCdsModeChangeCallback, passing null unregisters the callback.
setNavigationChangeCallback¶
method
cb: ((event: NavigationChangeEvent) => void) | null,
): void
Fires whenever the visible region changes in any way. event includes the trigger source (navigate / pan / zoom) along with the current transcript metadata.
- pan events are throttled on a ~100ms leading edge
- zoom events are debounced on a ~350ms trailing edge
renderer.setNavigationChangeCallback((e) => {
if (e.source === "navigate") {
history.replaceState({}, "", `?region=${e.chr}:${e.start}-${e.end}`);
}
});
NavigationChangeEvent
type
interface NavigationChangeEvent {
chr: string; // chromosome name, e.g. "chr1"
start: number; // start coordinate, bp
end: number; // end coordinate, bp
source: "navigate" | "pan" | "zoom"; // trigger source
gene_name: string; // gene symbol, e.g. "TP53"; empty string when no transcript
gene_id: string; // Ensembl gene ID; empty string when unavailable
transcript_name: string;// transcript name, e.g. "TP53-202"; empty string when unavailable
transcript_id: string; // Ensembl transcript ID; empty string when unavailable
}
setRnaModeChangeCallback¶
method
cb: ((enabled: boolean, info?: { tssPos: number; strand: "+" | "-"; chr: string; name: string }) => void) | null,
): void
setCdsModeChangeCallback¶
method
cb: (enabled: boolean, info?: { strand: "+" | "-"; chr: string; name: string }) => void,
): void
Note that this callback's parameter is non-nullable (does not accept null).
setCdsCanvasNavigationCallback¶
method
The callback fired in CDS mode by wheel-zoom / drag-pan on the canvas. Button-triggered pan/zoom go directly through panCdsView / zoomCdsView.
setOnImportCustomReference¶
method
Registers the "custom reference assembly complete" callback. After the user drags in local files via importCustomReference and confirms, the assembled IReferenceConfig is delivered through this callback.
Tooltip control¶
setTooltipTrigger / getTooltipTrigger¶
method
getTooltipTrigger(): TooltipTrigger
Sets / reads the tooltip trigger mode: "hover" / "click" / "off". Setting "off" immediately hides the current tooltip.
setTooltipMode / getTooltipMode¶
method
getTooltipMode(): TooltipMode
"detailed" (title + interval + all fields) or "compact" (condensed).
setTooltipEnabled / isTooltipEnabled¶
method
isTooltipEnabled(): boolean
The legacy toggle API, mapped internally to trigger: true ↔ "hover", false ↔ "off".
hideTooltip¶
method
Immediately hides and unpins the current tooltip.
Cursor / crosshair¶
setCursorEnabled / isCursorEnabled¶
method
isCursorEnabled(): boolean
setCursorMode / getCursorMode¶
method
getCursorMode(): CursorMode
"compact" / "detailed" / "each". See CursorMode.
Highlight visibility¶
setHighlightVisible / isHighlightVisible¶
method
isHighlightVisible(): boolean
Toggles the visibility of highlight regions. Does not clear the intervals — turn it back on and they are still there. To clear them, use renderer.highlightManager.clear().
setHighlightShowDistance / isHighlightShowDistance¶
method
isHighlightShowDistance(): boolean
Whether to overlay the ← width → width label on highlights.
Grid¶
setGrid / getGrid¶
method
getGrid(): GridDisplay
GridDisplay = "none" | "x" | "y" | "x+y".
Channel Label / Legend¶
setChannelLabelVisible / isChannelLabelVisible¶
method
isChannelLabelVisible(): boolean
setLegendStyle / isLegendVisible / getLegendStyle¶
method
isLegendVisible(): boolean
getLegendStyle(): "auto" | "text" | "colorbar"
style defaults to "auto".
"auto"— each channel uses its own default display"text"— force the[min, max]text to display"colorbar"— force the colorbar to display
Channel add/remove (convenience API)¶
The following methods are shortcuts to channelManager, with a UI confirmation dialog (suitable for user-initiated additions). For batch or silent operations, use renderer.channelManager directly.
addChannel¶
method
Pops up a preview dialog and appends a single channel after the user confirms.
addManyChannels¶
method
Pops up a batch confirmation dialog to add multiple channels at once.
importLocalFiles¶
method
Opens the local file import dialog. Automatically detects the format (BAM/CRAM/BED/BigBed/BigWig/VCF/GFF/FASTA), automatically matches index files, and automatically selects the plot type.
importRemoteUrl¶
method
urlOrList?: string | Array<{ url: string; name?: string; indexUrl?: string; index2Url?: string }>,
indexUrl?: string,
index2Url?: string,
name?: string,
): void
Opens the remote URL import dialog. Two usages:
- Single channel: pass
(url, indexUrl?, index2Url?, name?) - Batch: pass an array, where each entry is detected independently and confirmed in a batch
importCustomReference¶
method
Opens the custom Reference assembly dialog, where the user can supply FASTA / annotation / chromsizes / cytoband. Once assembled, the result is delivered through the callback registered via setOnImportCustomReference.
Transcript info¶
transcriptInfo¶
getter
gene_id: string;
trans_id: string;
trans_name: string;
gene_name: string;
trans_type: string;
gene_type: string;
} | null
Returns the metadata of the currently loaded transcript (from the reference catalog query result). The filterGene / filterTranscript fields within a Channel use this value to filter. Returns null when there is no transcript context.
Renderer state¶
getState¶
method
Returns the current IRendererState.
type
enum RendererStatus {
init = "INIT",
Loading = "LOADING",
Loaded = "LOADED",
Error = "ERROR",
uploading = "UPLOADING",
uploaded = "UPLOADED",
}
interface RendererError {
message: string;
code?: string;
channelErrors?: { [channelIndex: number]: string };
}
interface IRendererState {
status: RendererStatus;
error?: RendererError;
loadedChannels?: number;
totalChannels?: number;
}
Internal Managers¶
Each TranscriptBrowserRenderer instance exposes a set of internal Managers as read-only properties. They are not singletons; they are bound to that specific renderer instance.
| Property | Page | Description |
|---|---|---|
renderer.channelManager |
Channel manager | Channel CRUD for this renderer |
renderer.referenceManager |
Reference manager | The reference genome list for this renderer |
renderer.locusManager |
Locus manager | Snapshot and navigation of the current locus (mode / RNA / DNA / favourite) |
renderer.searchManager |
Search manager | Transcript / gene search (flat / grouped / by-level) |
renderer.highlightManager |
Highlight manager | The highlight intervals for this renderer |
renderer.headerPanelManager |
Header Panel manager | Enabling / disabling toolbar buttons and event dispatch |
historyManager / favouriteManager are global singletons
Unlike the instance properties above, historyManager and favouriteManager are singletons shared across the entire process, importable from the top level of @rbrowser/main. Multi-instance browsers share the same history and favourites.