Embed a Structure Viewer

Show a real, orbitable structure on a page outside Tako: a group website, a paper’s supplementary page, a lab notebook, internal documentation. The embedded viewer is the same renderer the app uses, not a picture of one.

The complete option and method contract is in the Viewer Widget Reference.

The smallest embed

Load the script once per page, then mark up a container with the structure URL. No JavaScript of your own is needed.

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

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

The file can be CIF, XYZ, extXYZ, POSCAR, or Gaussian cube. Serve it from the same origin as the page, or from an origin that sends permissive CORS headers.

Choosing how it looks

Every visual option is a data- attribute in the same spelling as the JavaScript API.

<div
  data-tako-viewer="/structures/nacl.cif"
  data-height="520"
  data-style="vdw"
  data-color-scheme="jmol"
  data-background="black"
  data-cell="true"
  data-axes="false"
></div>

An option you spell wrong is ignored with a console warning, so one bad attribute cannot blank the page.

Letting readers adjust the view

controls puts a settings button in the corner of the viewer and decides what it offers. Name only the controls that matter for the point you are making.

<div
  data-tako-viewer="/structures/nacl.cif"
  data-controls="style,colorScheme,background"
></div>

Use data-controls="all" for the full set.

Driving it from JavaScript

When the page needs to react to the viewer, or change it later, create the instance yourself.

<div id="viewer"></div>
<script>
  const viewer = Tako.viewer('#viewer', {
    src: '/structures/quartz.cif',
    height: 480,
    style: 'bTube',
    controls: ['style', 'background'],
  });

  viewer.on('select', (atom) => {
    document.querySelector('#readout').textContent =
      atom ? `${atom.element} #${atom.id}` : 'nothing selected';
  });

  viewer.ready.then(() => console.log('viewer is live'));
</script>

Change the look in place, with no reload and no camera reset:

viewer.set({ background: 'black', atomScale: 130 });

Swap the structure while keeping the same widget and its look options:

await viewer.load({ src: '/structures/nacl.cif' });

Playing a trajectory

A source carrying more than one frame gets a scrubber and a play button automatically. Drive it from the page when you want to synchronise it with something else:

viewer.setFps(12);
viewer.play();
viewer.on('frame', ({ index, count }) => {
  progress.textContent = `${index + 1} / ${count}`;
});

Embedding a captured view

A structure file carries geometry but no presentation, so the widget frames the camera and applies your options. To reproduce an exact view from Tako instead, including its camera, its layer visibility, and any isosurfaces, point src at a captured snapshot and ask for its camera:

<div data-tako-viewer="/views/relaxation.json" data-camera="snapshot"></div>

Snapshots come from Tako’s viewer outputs. The captured presentation is the starting point, and any option you set on the embed overrides it key by key.

Handling failures

A structure that cannot be fetched or parsed never throws into your page. The reason is shown inside the widget and delivered to any error listener.

viewer.on('error', (error) => report(error.message));

WebGL is required. Where the browser cannot provide it, the widget shows that in place rather than rendering an empty box.

Serving the script yourself

The bundle is one self-contained file with no external dependencies. To pin a version or avoid a third-party request, copy tako-viewer.js next to your own assets and point the script tag at your copy.