Guides

Build on the canvas

A connected AI agent is the fastest way to build a dashboard. For that path, read Connect your AI agent. This guide is the manual path: what you can do with a click or a form, and where you need JSON instead.

The whole dashboard is one piece of JSON. The canvas and the Source panel show that JSON in two ways. When you drag a block, its position changes in the JSON. When you apply JSON, the canvas changes.

Before you start

Open a dashboard that you can edit, and set the mode switch in the header to Edit. A phone-size window stays in view mode. To edit, use a desktop or tablet window.

When you are signed in, a dashboard saves itself to your account as you edit. It is private until you publish it: see Share a dashboard. When you are not signed in, your dashboards stay in this browser only. If you clear the browser or change devices, they are lost. Sign in to save them to your account.

Start on the empty canvas

An empty dashboard shows a short walk under the title Start your dashboard:

The walk shows only the steps that you can take now. While the dashboard has no data:

1. Upload a file — opens the file picker and imports the picked file. This step leads.
2. Connect BigQuery — opens the Data workspace on a new BigQuery datasource. The step shows when you can run BigQuery: sign in first.
3. Connect to a shared datasource — opens the Data workspace on the datasource library, where each shared datasource shows its description. The step shows when you are signed in and the library holds a datasource that you can use.
4. Connect an AI agent — opens the Connect-an-agent panel. The step goes away after you connect an agent.

After a datasource has rows, Make a chart leads the walk and inserts a chart block. The data steps become one line under it: Add more data.

The fastest start is a data file. Drop a CSV, Excel, JSON, or Parquet file anywhere on the canvas. The Data workspace shows the file's columns and rows first. Select Create datasource, and a table block bound to the new datasource appears where you dropped the file. If the canvas cannot take the file, a notice says why and what to do first. For the other ways to bring data in, such as a paste, a query, or a Google Sheet, read Bring data in.

Add a block

In edit mode, the header holds the block palette: a Chart button and an Add menu.

1. To add a chart, select Chart.
2. To add a block of another type, select Add, then select the type. Each type in the menu has one line that says what the block is.

The new block appears at the center of the view, selected, with its editor open.

• Chart — one chart drawn from a datasource's saved rows.
• Scorecard — one number: a column reduced over the rows, with an optional delta and sparkline.
• Table — the rows themselves, paginated, with format rules.
• Sankey — a flow diagram over two columns: where something came from and where it went, drawn as stages with ribbons between them.
• Control — a filter, a slider or a field list bound to a param, the dashboard's named value.
• Note — markdown text.
• Article — starts an article beside the canvas and places a card for it on the canvas (Write up a finding in an article).
• Image — a picture from a web address.
• Shape — a drawn rectangle or ellipse with a label, for annotation.
• Section — a titled region that carries the blocks inside it.
• Frame — a named sheet that a reader reads as one page (Make pages with frames).
• Connector — a line between two blocks. The Add menu has no connector. Add a connector in the Source panel, or ask an agent.

A composite chart, such as facets, repeats, or side-by-side views, needs JSON. Paste its spec into the spec editor of a chart block, and the chart shows the composition.

Shape a chart where it stands

Select a chart, and small authoring blocks appear around the edges of the canvas. The mark and the position channels are along the top. The other channels, the decorations, Tooltip, Comparison, and Code are down the left. Each authoring block shows its current setting, and opens one popover with the controls for that setting.

1. If the chart is blank, pick a chart type from the grid in its body. In a short block, such as a new chart, the grid shows every type as one flat set of tiles. In a taller block, and in the popover of the Chart type block, the grid groups its templates by intent: Compare amounts, Change over time, Part-to-whole, Relationship, Distribution.
2. If you picked Bullet or Combo, open Properties. For a bullet, pick the Category, the Actual and the Target fields. For a combo, pick the X axis, the Bars and the Line fields. A number field adds up per category; change its aggregate below the field.
3. Open a channel block, such as X, Y, or Color, and pick a field. The popover also holds the field type, the aggregate, and the bin or time unit that fits the type. The field type uses the words of the Data panel: Number, Category, Ordered, and Time. On a number field, one click on sum or avg sets the field and the aggregate together. The picker also offers the datasource's measures: pick a measure such as ROAS, and the chart computes it per category.
4. To bind a field by drag, open Properties. Drag a field from its Fields group onto a channel block.
5. To change the mark and its settings, open the Mark block.
6. To sort a category axis, use the popover of that channel.
7. To show the value of each mark, turn on Labels.
8. To add a reference line, open the Reference line block and select Add line. The new line shows the average of the measure. You can change each line to a fixed value or a statistic.
9. Set the tooltip in the Tooltip block: Off, Chart fields, or a custom field list.
10. To draw the series over an earlier period too, open the Comparison block and turn on Compare periods.

The Code block lists what the spec holds beyond these controls, such as transforms, selections, and extra channels. It also opens the spec editor. If you layer a spec by hand beyond labels and reference lines, the authoring blocks close, and you edit that chart as JSON. The Properties panel holds the settings that are not encodings: the datasource, Filters, and Cross-filtering.

Make a scorecard

You build a scorecard on the canvas like a chart. Select one, and its own authoring blocks appear: Value along the top, and Comparison, Sparkline, and Code down the left.

1. Add a scorecard from the palette. If the dashboard has several datasources, pick one in the Properties panel.
2. Pick the field in the body of the scorecard. Measures are first in the list.
3. Open the Value block to change the field, the reducer (Summarize by — sum, mean, min, max, count, last, or first), the number format, and where the status color shows.
4. In the Comparison block, turn on Compare for a delta line: against an earlier period of a date column, a target number, or a second column.
5. In the Sparkline block, turn on Show trend and pick the column under Trend over. On a date column, set Granularity — Auto, or a calendar unit from day to year. Pick the Style: Line, Bars, or Area.

If the number is a ratio, such as revenue per order or a conversion rate, define a measure on the datasource and pick it. Measures are first in the Field picker. A measure carries its own formula, so the reducer does not apply. The label and the format of the number come from the metadata of the field. The Number format row in the Value block overrides them. The Properties panel holds the datasource and the Filters group.

Make a table

1. Add a table from the palette. A fresh table shows every column of its datasource.
2. To group the rows, add a field under Rows and a number under Values. Each value carries its own reducer, so one table shows a sum beside an average. In the value's picker, the buttons on a column's row set the field and the reducer in one click.
3. To spread the values across the top as a crosstab, add a field under Columns. You can add up to two fields. A crosstab reads best with one value per cell, because each extra value repeats under every column key. The Columns group says so.
4. If Rows and Values are empty, the table shows the rows of its datasource. Then use Columns shown to hide, reorder, and configure each column: alignment, format, what the cell shows, and a footer reducer.
5. To set a column's width, drag the right edge of its header. Double-click the edge to make the width automatic again. Columns without a set width share the remaining space.
6. To turn a column's values into links or pictures, set its cell to a link or picture cell. The Address field takes a template whose {column} placeholders read the values of that row. If the field is empty, the value of the cell is the address.
7. Add format rules in the Format section. Add rule colors the cells, or whole rows, that match a condition. Add scale colors a numeric column on a color scale, and Add bar shows a bar beside each number. Each new rule is complete and applies at once. On a column with both positive and negative values, a scale divides at zero, so positive and negative values show apart with no setting.
8. Turn on the totals you need in Totals: subtotal rows, a total row, and a total column. Each total calculates from the rows of its own group, and not from the cells above it. A total over an average or a measure therefore does not equal the sum of those cells. When a total is on, the group says so and names the values it affects.

Table options holds the sort, the page size, Wrap long text, and Keep first columns in place. Each folded group names its settings, so you can read the whole table setup without opening a group.

Arrange the canvas

• Move — drag a block by its header. Positions snap to the grid of the dashboard.
• Align — while you drag, the edges and centers of the block snap to those of other blocks within 8 screen pixels. A thin guideline marks each match. Alignment to a block takes priority over the grid.
• Resize — point at a block or select it, then drag a corner square or a side. When you drag the top or left side, the block moves, and the opposite side stays in place. The edge you drag snaps to the edges of other blocks, then to the grid.
• Select several — Shift+click adds a block, Shift+drag on empty canvas sweeps a selection rectangle, and ⌘/Ctrl A selects every block. A section joins the rectangle's selection only when the rectangle encloses the whole section, so a sweep inside a section selects its blocks without the section. A drag on any selected header moves the whole set as one undo step.
• Nudge — arrow keys move the selection one grid step, Shift+arrows five.
• Duplicate and delete — ⌘/Ctrl D duplicates, the Delete key deletes, and both are also in the ⋯ menu of the block. A delete does not ask first. A notice names the block and the undo key.
• Paint order — where blocks overlap, Bring to front and Send to back in the ⋯ menu reorder them.
• Sections — the title chip of a section is its handle. Drag the chip, and the blocks of the section move with it. Drag a block in or out to change membership. Clicks go through the body of a section, so only the chip or the border selects it. A control can apply to one section only, and then filters the data blocks of that section.
• Connectors — a connector points from one block to another and follows them as they move. Click its line to select the connector, and press Delete to remove it. Add a new connector in the Source panel.

Make pages with frames

A frame is a named sheet on the canvas. A reader can switch from the canvas to Pages and read one frame at a time, as one page of a report.

To select a frame, click its name or its border. A click inside the frame selects the block under the pointer. The frame's form opens in Properties on the right icon rail.

Do these steps one time for each page:

1. In edit mode, select Add in the header, then Frame. A 16:9 frame named New frame appears at the center of the view, behind the other blocks. A new frame takes no block: a block that it covers stays on no frame.
2. Drag the frame by its name to an empty part of the canvas, so that it does not cover another frame.
3. Double-click the name above the frame, type the name of the page, and press Enter. The name is also the title of the page tab.
4. Drag each block onto the frame. A block belongs to the frame when its center is on the frame. A section brings its blocks with it.
5. To change the shape, select the frame, then select 16:9, 4:3, or A4 in Properties. You can also drag a corner or a side of the selected frame.

The pages follow the order in which you added the frames. To move a page, select its frame, then select Move earlier or Move later in Properties.

To see the pages as a reader sees them:

1. Set the mode switch in the header to View.
2. Select Pages in the Canvas | Pages switch over the top of the canvas. Each frame is a tab, in page order.
3. Open Findings on the right icon rail. Findings names each block that is on no frame. A block on no frame does not show in the pages. Drag each such block onto a frame.

A reader opens the dashboard on the canvas, and on a phone on its pages (Read a dashboard page by page).

• Drag a frame by its name, and its blocks move with it. A frame that you move over a block does not take that block.

• Delete a frame, and its blocks stay on the canvas. Duplicate a frame, and its blocks are copied with it.
• Hide from the page view takes a frame out of the pages. The canvas shows it, faded. A hidden frame is not private: every reader of the dashboard sees it on the canvas.
• Present, in the page view, shows the pages fullscreen and fits the whole frame on the screen. A long or wide frame shows smaller there, and its name carries the tag Shrinks in Present.

Undo and redo

⌘/Ctrl Z undoes, ⌘/Ctrl ⇧ Z redoes. One gesture is one step: a whole drag, a whole text edit, a burst of nudges. When another person or an agent edits the same dashboard, your undo does not reverse their work. If their edit replaced what an undo step would change, the app skips that step, and a notice says so. Inside a text field, the keys undo and redo the text of that field.

When someone else changes the dashboard

Another editor, an agent or the scheduled refresh can change the dashboard while you have it open. The dashboard takes the change in place, and your own unsaved edits stay. A notice names who changed what, for example "[email protected] changed 2 charts and the title." The changed blocks light up for a moment. To see them again, select Show changes in the notice.

While an agent works, the header shows Agent editing, and the blocks that the agent changed have a dashed outline. When the agent stops, one notice names all of its changes. If the change came from your own agent or from your own other tab, the notice also has Undo. Undo takes back only the parts of that change, and the dashboard saves the result. To undo the work of another person, restore an earlier version in Version history (Dashboard settings).

The label beside the title can read Catching up… for a moment. Someone else saved just before you, and the app joins your edits to theirs before it saves.

Put your edits back after a collision

A collision is when you and someone else changed the same part of the dashboard: the same block, datasource, param, title or theme. The dashboard then shows their version of that part. Before it does, the app keeps a copy of your whole dashboard in version history, labelled Set aside. A notice names the part and stays until you close it.

1. To see your version, select Compare in the notice. Your copy opens read-only. The outlined blocks are different from the dashboard now, and the banner names the other parts that are different.
2. To take back your version of the parts that collided, select Put mine back. The rest of the dashboard stays as it is.
3. To go back to the dashboard without a change, select Back to current.

After Put mine back, a notice names the parts that came back. The other version stays in version history. To take back the whole copy instead, open Version history, select the Set aside row, and select Restore this version. A set-aside copy stays in the history for 30 days.

If the notice says that the app could not keep a copy of your edits, do nothing. Your screen stays as it is, your edits stay in this browser, and the app tries again in a moment.

Write and decorate

Notes

To write in a note, double-click its body, or select the note and press Enter. The text is markdown: headings, lists, tables, quotes, code, links, and pictures with ![description](address). The note saves as you type. Escape closes the editor and keeps the text. Markdown that the app cannot draw stays as plain text.

Images

An image block without an address shows its own form. Paste the address into Image URL and select Set image. If the picture does not load, the form shows again, with the address kept and the error named.

Block titles

To rename a block, double-click its title or press F2. If the title is blank, the block shows its id. The form of a chart adds the Title choice: in the header, drawn on the chart itself, or hidden. On other block types, only the Source panel hides a title.

Write up a finding in an article

An article is text beside the canvas, with charts placed in it. Each chart in an article keeps the filters you set when you placed it, so a reader sees your finding without setting the filters. You need edit access to the dashboard.

1. On the canvas, set the filters and the chart options that show the finding.
2. Open Articles on the right icon rail and select Write an article. You can also select Article in the header's Add menu, which also places a card for the article on the canvas.
3. Type the title and the text. The text is markdown, like a note.
4. Put the cursor where the chart goes. In Add a chart, pick the chart.
5. Select Done to read the article as a reader sees it.

The chart appears in the text with the filters from the canvas. The Views list names each chart and what it keeps. To change what a chart keeps, set the filters on the canvas again, then select Record again on that row.

When the data under an article changes, the article shows a notice that the text may no longer match the charts. Read the text again and correct it, then select Mark as current. A refresh that returns the same rows shows no notice.

Edit the JSON where the form ends

Open the Source panel from the right icon rail, or press ⌘/Ctrl J. The panel shows the whole dashboard as JSON, and follows the canvas until you type. Your typed edits wait for Apply. Apply checks them first: if the JSON is not valid, or the dashboard would be broken, the panel shows the error and changes nothing. Revert discards your typed edits.

For one block, each block form has Edit as JSON at its foot: the same block as raw JSON, and Apply works the same way. A note's form holds its text as markdown, and the note changes as you type. Composite chart, image, shape, section, and connector blocks have no form. Their Edit action opens the JSON of the block.

To open the spec editor of a chart:

1. Select the chart.
2. Open Properties from the right icon rail.
3. Select Edit spec at the top of the panel.

The Code block of the chart also has Edit spec. For a composite chart, Edit spec is in the ⋯ menu of the block header.

The spec editor works differently from the other JSON editors. The chart redraws on the canvas a moment after you stop typing, so you see the spec take shape. Apply still saves: until you select it, nothing reaches the dashboard, and Revert or Close discards the draft. While the JSON is incomplete, the chart shows its last good version, dimmed, with the problem written over it. The authoring blocks of the chart hide while you type, and come back when you apply, revert, or close.

The editor knows Vega-Lite. It completes property names and values from the schema. Where the spec names a column, in a field or a groupby value, it completes the columns of the chart's datasource, each labeled with its field type. Put the pointer on such a column name and keep it there. A peek opens with the type and the profile of the column, the same line that the Data workspace and the field pickers show. A name that is not a column of the datasource, such as a column that a transform calculates, opens no peek.

A formula is the text of a calculate, filter, test, or expr value, and it gets help of its own. Type datum. to get the list of columns. Where a name starts, the editor completes the functions of the Vega expression language. Inside a function call, it shows the arguments of the function. A formula that does not parse gets a red underline, with the reason.

The editor lays the spec out compactly: an array or an object stays on one line until the line is longer than 80 characters. Each paste lays out the whole spec again. To lay it out on demand, press Shift+Alt+F. A spec that does not parse stays as you typed it.

Above the spec, the editor lists the warnings from Vega-Lite at the last draw of the chart. A sort that a layer drops is an example. A chart that draws cleanly lists nothing.

Some settings exist only in the JSON: a chart spec layered by hand, selections and custom transforms, composite charts, connectors, the thresholds and value mappings of a field, and each detailed setting that a form names as JSON-only. What needs the Source panel or an agent keeps the current list.

The Source panel edits the same JSON that an agent edits, and everything on the canvas is in that JSON. When hand edits become slow, connect an agent and describe the change instead.