‹ Phoria demos

Getting started

Two short walk-throughs to get you going: first a simple 3D scene, then a live dashboard of 3D charts. Every step is a complete program running right beside the example code so you can see exactly what each line does. You can copy any step as a single HTML file, or open it in CodePen and play with it there. It should take about fifteen minutes from start to finish.

Setting up

There's nothing to install! A single HTML file is all you need. An import map tells the browser where to find 'phoria2' (here it's a CDN, pinned to version ), and then your code imports from it just as it would from npm. Here's the first step below as the complete file:

Save it as index.html and open it in your browser. The Copy as one page button on every step gives you a file just like this one, ready to run.

Part 1: A first scene

1. A box on the page

A View draws into a canvas - you can pass it the element itself, or a CSS selector to find it. Whatever it draws lives in its scene. A Mesh is a shape (its geometry) with a look (its material), and the material is just a plain object of options.

You'll notice there's no camera or light in the code, yet there's a lit box on screen. When you don't give it a camera, the View looks at the scene from the front, slightly to the right and above, and fits everything in. With no lights, it lights the scene itself and mentions this in the console. The View also only draws when something changes - so once this still picture is on screen it costs nothing to render until it changes - this is different to most 3D libraries.

2. Light and motion

Setting orbit: true lets you move the view around: drag to orbit, right-drag to pan and scroll to zoom. A DirectionalLight shines like the sun, with all its light going the same way - its direction is the way the light travels, which here is down and away from you. scene.add() hands back whatever you added, so you can keep hold of it for later.

view.start() calls your function once every frame, passing in the seconds since the last one (dt). Multiplying your movement by dt keeps the speed the same on any screen, however fast it refreshes - here the cube turns at 0.6 radians a second.

3. Materials, a floor and shadows

Positions are in metres, with Y pointing up. roughness goes from a perfect mirror at 0 to completely matte at 1, and metalness: 1 turns a material into metal, which reflects its surroundings tinted by its own colour. environment: 'studio' gives it a built-in photo studio to reflect (you can use your own .hdr file too). Shadows need three things: the light casts them, the shapes cast them, and the floor receives them.

4. Labels

A Label is an HTML element tracking a point in 3D. That means it's sharp at any size, you can select its text and you can style it with CSS - this step has a little CSS in its HTML to show that. Because it's added to the cube rather than the scene, the label follows the cube wherever it goes and its position is measured from the middle of the cube.

5. Hover and click

highlight tints whatever is under the pointer, and tooltip is given a hit - a description of what's under the pointer - and returns what to show for it. view.on('click') gets a hit too, or null if you clicked on empty space. The floor is set to pickable: false, so the pointer passes straight through it.

6. A shader hook

For anything the material options can't do, shader lets you run a few lines of your own GLSL inside phoria2's shader. Here the vertex hook moves each point of the floor up and down into ripples (more segments gives it more points to move), and bends its normal n to match, so the lighting and shadows follow the ripples too. uTime is the View's clock, and a hook that uses it keeps the scene moving without you writing a frame loop. Hooks can change colours as well - the reference lists everything each hook can use, along with some recipes you can copy.

Part 2: A chart dashboard

1. A bar chart from rows

chart(), from phoria2/charts, turns rows of data into a chart, complete with axes, ticks, a grid, a legend and tooltips. You tell it which fields to use: x and z for the rows of bars, y for their height and color for their colour, and tooltip: true shows every field when you hover over a bar. view.frame() moves the camera so the chart fits nicely in view.

A chart is just an ordinary node in the scene, so you can orbit around it, hover over the bars, and click the swatches in the legend to hide or show a region.

2. Live data

chart.update(rows) moves the bars to their new figures. A field can also be given as an object, with a title and a format for the axis and tooltips - here the sales figures are in thousands of pounds.

The View draws while the bars are moving, then stops again until the next update - so a dashboard left open costs almost nothing in between refreshes.

3. A dashboard of views

Each tile is its own View on its own canvas, laid out with ordinary CSS grid, and you can have as many as you like on a page. Browsers only allow around 16 WebGL contexts, so phoria2 gives the first four their own and draws the rest through one shared context - each one is still its own canvas though. framing: 'both' keeps the whole chart visible in its tile, whatever shape the tile ends up. This happens automatically, you just use a canvas for each.

All three charts are made from the same rows - only the mark changes, to bars, lines and areas stacked up to a total. A small tile() function saves writing the same setup three times.

4. Linked views

Clicking a bar gives you a hit whose datum is the row behind that bar. chart.filter() only shows the rows a function keeps, so clicking a bar narrows the other two tiles down to its region, and clicking on empty space passes null so they show every region again. The filter keeps working as the data updates.

Copyright © Kevin Roast 2013-2026 · GitHub · npm