Viewer Widget Reference

Page type: Reference

On this page

Loading the script
Declarative embedding
Programmatic embedding
Source options
Layout options
Look options
Behaviour options
Instance API
Events
Behaviour notes

The viewer widget puts a live, interactive Tako structure view on any web page. It mounts the same renderer the Tako app uses, so an embedded structure shows the same atom impostors, colour schemes, lighting, and trajectory playback as the app itself.

For a task-oriented walkthrough see Embed a Structure Viewer. This page is the complete contract.

Loading the script

<script src="https://tako.atom.li/embed/tako-viewer.js"></script>

The bundle is one self-contained file. It defines window.Tako and makes no further network request except for the structure files you point it at.

Declarative embedding

Any element with a data-tako-viewer attribute is mounted automatically once the document is ready. The attribute value is the structure URL.

<div data-tako-viewer="/structures/quartz.cif" data-height="480"></div>

Every option below is available as data-<option>, in the same spelling as the JavaScript API. HTML attribute names are case-insensitive, so data-colorscheme and data-color-scheme both reach the colorScheme option.

Programmatic embedding

const viewer = Tako.viewer('#host', { src: '/structures/quartz.cif' });
await viewer.ready;

`Tako.viewer(target, options)`

Creates and mounts a viewer. target is a CSS selector or an element. Returns a TakoViewer instance immediately; loading continues in the background.

`Tako.viewAll(root?)`

Mounts every not-yet-mounted [data-tako-viewer] element under root (the document by default). Already-mounted elements are skipped, so it is safe to call after a single-page app renders new content. Returns the instances it created.

`Tako.get(element)`

Returns the instance mounted into element, or undefined.

`Tako.version`

The widget contract version, currently "1". It changes only on a breaking change to the contract documented here.

Source options

Give exactly one source. When more than one is present, snapshot wins over data, which wins over src.

Option	Type	Meaning
`src`	string	URL of a structure file, or of a `.json` file holding a captured Tako view. Format is detected from the extension.
`data`	string	Structure file contents supplied inline. Requires `format`.
`format`	string	`cif`, `xyz`, `extxyz`, `poscar`, or `cube`. Required with `data`; with `src` it overrides extension detection, which is what a download URL carrying no filename needs.
`snapshot`	object	A `tako-viewer-snapshot` object captured by Tako, mounted verbatim.

A .json URL is read as a captured snapshot. Anything else is parsed as a structure file.

Layout options

Option	Type	Default	Meaning
`height`	number or CSS length	`420px`	A bare number is read as pixels.
`width`	number or CSS length	fills the host
`title`	string	the structure’s own title	Caption shown by the viewer.

Look options

Each of these sets how the scene is drawn. Every one is also a valid entry in controls.

Option	Type	Values
`style`	string	`flat`, `skeletal`, `vdw`, `bTube`, `bubble`
`colorScheme`	string	`vesta-soft`, `jmol`, `kessoku`
`material`	string	`modern-matte`, `classic-matte`, `glossy`, `metallic`, `2-5d`, `2d`
`background`	string	`light`, `white`, `black`
`atomScale`	number	Atom radius, in percent. `100` is the default size.
`bondScale`	number	Bond radius, in percent.
`bondColorMode`	string	`bicolor` splits a bond at its midpoint, `unicolor` paints it one colour.
`edges`	boolean	Outline atoms and bonds.
`bonds`	boolean	Draw bonds.
`cell`	boolean	Draw the unit cell box. Periodic structures only.
`axes`	boolean	Draw the orientation axes.
`labels`	boolean	Draw per-atom element labels.
`polyhedra`	boolean	Draw coordination polyhedra.

An unrecognised value is ignored with a console warning rather than failing the embed, so one bad attribute cannot blank out a working page.

Behaviour options

Option	Type	Default	Meaning
`autoRotate`	boolean	`false`	Spin the scene continuously.
`camera`	string	`fit`	`fit` frames the structure on load. `snapshot` keeps the camera stored in a captured snapshot, and has no effect on a structure file, which carries no camera.
`controls`	boolean, string, or array	none	Which controls the reader may adjust. See below.

`controls`

Controls appear behind a settings button in the corner of the viewer. Accepted forms:

Value	Result
`true` or `"all"`	Every control.
`false`, `"none"`, or `[]`	No controls. This is the default for a structure file.
`"style,background"` or `["style", "background"]`	Just those controls.
`"snapshot"`	Keep whatever panel a captured snapshot was captured with. This is the default when the source is a snapshot.

Valid entries are the look option names: style, colorScheme, material, background, atomScale, bondScale, bondColorMode, edges, bonds, labels, axes, cell, polyhedra.

Instance API

Member	Returns	Meaning
`element`	element	The element the widget was mounted into.
`ready`	Promise	Resolves once the structure is on screen. Rejects if it cannot load.
`load(source?)`	Promise	Replaces the structure. Takes `src`, `data`, `format`, `snapshot`, or `title`. Look options persist across the swap.
`set(options)`	instance	Applies look options to the mounted scene in place, without a reload. Also accepts `autoRotate`, `height`, and `width`.
`autoRotate(on?)`	instance	Starts or stops the spin.
`frameCount()`	number	Trajectory frames. `1` for a static structure.
`currentFrame()`	number	Index of the frame on screen.
`setFrame(index)`	instance	Scrubs to a frame, clamped, pausing playback.
`play()` / `pause()`	instance	Trajectory playback. No-op for a static structure.
`setFps(fps)`	instance	Playback rate.
`camera()`	object or null	Current camera state. `null` before the viewer mounts.
`resetCamera()`	instance	Re-frames the structure, undoing the reader’s orbit and zoom.
`destroy()`	void	Tears the viewer down and releases its WebGL context.

Every method that returns instance can be chained.

Events

viewer.on('select', (atom) => console.log(atom));

Event	Payload
`ready`	The instance.
`error`	An `Error`. Also shown in place inside the widget.
`select`	`{ id, element, position }` for the clicked atom, or `null` when the selection is cleared.
`camera`	The camera state, on every camera change.
`frame`	`{ index, count }`, on every trajectory frame change.

off(event, listener) removes a listener.

Behaviour notes

WebGL is required. Where it is unavailable the widget shows the failure reason in place and emits error.
Cross-origin structure files must be served with permissive CORS headers, since the widget fetches them from the page’s origin.
A failed load never throws into your page. ready rejects, error fires, and the reason is shown inside the widget. Attach an error listener or catch ready if you want to react.
Concurrent loads settle in order. If load() is called again before a previous load finishes, only the newest one is applied.