Guides

Build on the canvas

A connected AI agent can build a dashboard for you. 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

On an empty dashboard, you see a few first steps under the title Start your dashboard:

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

1. Import a file — opens the file picker and imports the picked file. This step is first.
2. Connect BigQuery — opens the Data workspace on a new BigQuery datasource. The step shows when you can run BigQuery: sign in first.
3. Use a shared datasource — opens the Data workspace on the datasource library, where each shared datasource has its description. The step shows when you are signed in and the library holds a datasource that you can use.
4. Read a Google Sheet or URL — opens the Data workspace on a new Sheets/URL datasource, where you paste the link. You need no account for a Google Sheet shared as “anyone with the link”.
5. Connect an AI agent — opens the Connected agents section of your Settings page. The step goes away after you connect an agent.

After a datasource has rows, you can pick from up to five starter charts made from that data, under Start from a chart of and the datasource's name. Each starter is a small live drawing. To place starter charts:

1. Tick the starters that you want. The first one is ticked. To see a starter larger, point at it or move the keyboard focus to it.
2. Select Place the chart, or Place N charts when you ticked more than one.

The charts appear on the canvas, three to a row, and each one is an ordinary chart that you edit. For a chart with no starter, select Make a blank chart. When no starter fits the data, Make a chart is the first step instead. Either way, the data steps become one line under it: Add more data.

To start with a data file, drop a CSV, Excel, JSON, or Parquet file anywhere on the canvas. You see the file's columns and rows in the Data workspace 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, you see a notice with the reason 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.

Make one chart

Make one chart when you want a chart and not a dashboard. The chart opens in the Chart workspace. You share and publish a chart the way you share and publish a dashboard.

You need nothing first. Without an account, the chart stays in this browser.

1. On the Charts page, select New chart. On the landing page, select Try it without an account.
2. Start the chart one of three ways:
   • Drop a CSV, Excel, JSON or Parquet file on the dashed box, select Import a file, or select Paste rows. The Data workspace shows the columns and rows. Select Create datasource.
   • Paste a Vega-Lite spec in Paste a Vega-Lite spec, and select Make the chart. Rows inside the spec move to a datasource of their own.
   • Select an example. It draws on the sample data.

The chart opens in the Chart workspace. It lists on the Charts page, apart from your dashboards, and stays there if you add a note or a second chart.

If a pasted spec reads its rows from an address, the box says what to do. Download the file and drop it, or add the address in the Data workspace first.

Work on one chart in the Chart workspace

The Chart workspace shows one chart large, its code on the right, and its rows under it. To open it, select ⋯ on a chart in edit mode, then Open in Chart workspace.

• Type in the code pane. The chart draws the code when you pause. Code that parses is saved. Code that does not parse saves nothing, and the chart names the error.
• Inside "transform": [ ], open the completion list to add a step, such as a filter or a running total. Tab moves through the parts of the step.
• Under the chart, As drawn shows one row per mark. As it arrives shows the datasource's rows with the chart's filters.
• To undo a save, use undo, or put back an earlier version.

Select ‹ Canvas to go back to the canvas.

Publish one chart from a bigger dashboard

When you publish a dashboard, every chart and every row of every datasource is public. To publish one chart alone, copy it to a dashboard of its own first.

1. On the chart, select ⋯, then Copy to its own dashboard. The Chart workspace also has this button.
2. The copy opens in the Chart workspace. It holds the chart and only the data it reads. Select Publish.

The copy does not change when you change the original. To publish a change, change the copy and publish it again. Publish shows only when you are signed in and this site allows publishing.

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 a one-line description of the block.

You can also press ⌘ K on a Mac, or Ctrl K elsewhere, and type the block type, such as "add a chart". The same list runs the other editing commands and shows each command's key (Run a command from the keyboard).

The new block appears at the center of the view, selected, with its editor open. When another block is already there, the new block takes the nearest free place, so it never covers one. When that place is outside the view, the canvas moves to it.

• 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. Open a chart block in the Chart workspace and paste its spec into the code pane. The chart shows the composition.

Shape a chart where it stands

Select a chart, and small authoring blocks appear around it, in four zones:

• The data bar on the top edge of the chart: Data, Fields and Filters.
• The Marks card at the left of the chart: the mark in its header, then a row for each channel in use, such as Color or Tooltip. One line names the channels that are not in use. Select it to show them.
• The Chart card under the Marks card: Title, Comparison, Reference line, Cross-filter, Block size and Code. The card stays folded until you select its name.
• The axis blocks: X under the chart, and Y at its right.

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 Chart type in the Marks card's header, the grid groups its templates by intent: Compare amounts, Change over time, Part-to-whole, Relationship, Distribution.
2. If you picked Bullet or Combo, select Settings in the chart's header. The chart's form opens beside it. 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. If Color is not in the Marks card, select the line of unused channels first. The popover opens on the side away from the chart, so it does not cover the chart. In the popover, the Field row shows the field as a pill: a glyph for its type, its name, and its aggregate at the right end. An empty pill reads Choose a field….
4. To pick a field, select the name on the pill. The field list opens: the datasource's columns, then its measures. Type to narrow the field list. Select a field, or press Enter to take the highlighted one. To bind a field by drag, drag it from Fields onto the pill.
5. To set a number field and its aggregate in one click, move the pointer over the field in the field list. Select sum or avg at the right end of its row.
6. To pick a measure of the datasource, such as ROAS, select it in the field list. The chart computes the measure per category. The measure carries its own aggregate, so the aggregate on the pill reads None.
7. To change the aggregate, select it at the right end of the pill, and pick one from its list. The list holds None, Count (records), and the aggregates that the field type allows. Channels such as Detail and Shape take no aggregate, and their pill shows none.
8. To change the field type, select a word in the Type row under the pill: Number, Category, Ordered, or Time. These are the words of the Data workspace. Under the Type row, a Time field has Time unit, and a Number field has Bin into ranges.
9. After each pick, the chart redraws at once. The channel block names the field and its aggregate, such as sum(sessions). The popover stays open. To close the popover, press Escape, or select a point outside it.
10. To remove the field from a channel, select Remove, the × at the right end of the pill. The chart redraws without that channel. In the Marks card, the channel goes back to the line of unused channels. If the aggregate is Count (records), the channel keeps the count of records.
11. To bind a field by drag, open Fields in the data bar. Drag a field from its list onto a channel block.
12. To change the mark and its settings, open the mark in the header of the Marks card.
13. To sort a category axis, use the popover of that channel.
14. To show the value of each mark, open Labels in the Marks card and turn it on. If Labels is not in the card, select the line of unused channels first.
15. To add a reference line, open Reference line in the Chart card and select Add line. The new line shows the average of the measure axis. You can change each line to a fixed value or a statistic.
16. Set the tooltip in Tooltip in the Marks card: Off, Chart fields, or a custom field list. Turn on Rich tooltip there to show every line at one date on a line over dates, or a bar's rank and share of the total, with Keep only and Exclude for your readers (see Read the values under the pointer).
17. To draw the series over an earlier period too, open Comparison in the Chart card and turn on Compare periods.
18. On a chart with dates on an axis and a summed value, viewers can switch the dates between day, week, month, quarter and year. To keep the chart at the grain you made it, open Date grain in the Chart card and turn off Viewers can switch the date grain.
19. To show the measure axis as a running total, a change from the previous value, a share of the total, a rank, a percentile, or a moving average, open the block of the measure axis and select a mode in Show as. In Computed over, select where the computation restarts: Each series, Each X value (for example, each region's share of its month), or All marks. To show the plain values again, select Value.

The Code block in the Chart card lists what the spec holds beyond these controls, such as transforms, selections, and extra channels. Its Edit spec opens the chart in the Chart workspace, with the cursor in the code pane (see Edit the spec of a chart). If you layer a spec by hand beyond labels and reference lines, the authoring blocks close, and you edit that chart as JSON. A chart has no separate settings form.

Draw a map

A map draws a value per country or region, a dot per place, or how many rows fall in each cell of a grid. You need edit mode (Before you start) and a datasource whose rows name the places in one of these ways:

• A code per row: a country's three-letter ISO code, such as UKR, or a region's ISO 3166-2 code, such as UA-30. US states use their two-letter postal code, such as CA.
• A latitude and a longitude in degrees, or a city name, for a dot per row.
• A cell per row, written as GeoJSON text by a query, and a count, for a density map. Your agent writes that query from the help it reads (Work with your agent).

1. Select Chart in the header (Add a block). On the new chart, you see the chart types.
2. Under Location, select Map, Point map or Density map. The chart draws the world's outlines, and the Marks card at the chart's left has a Map row (Shape a chart where it stands).
3. Select the Map row, and pick the columns:
   • For Map, the Outlines and the Code column.
   • For Point map, Coordinates with the Latitude and the Longitude column, or City names with the City name column.
   • For Density map, the Cell column.
4. To color the map, drag a number column onto Color in the Marks card. On a point map, drag one onto Size to size the dots.

The map draws a shape or a dot for each row it can place.

To draw a country's regions, pick that country in Outlines, such as Ukraine regions. Region codes draw nothing on the world's countries. On every map that Arkush ships, Crimea is part of Ukraine.

A city name is matched against about 7,000 cities and towns of note, in English or Ukrainian. If several places share a name, such as Springfield, the name draws no dot. In the Map row, you read which rows draw no dot. To fix them, add a column with each place's two- or three-letter country code, and pick it as Country in the Map row. A village name draws no dot either: give its latitude and longitude instead.

Zoom a map

You can zoom any map, in view mode and in edit mode.

1. Click the map. An outline around the map means that the map takes the scroll.
2. Scroll or pinch to zoom, and drag to move the map.
3. Press Escape or click outside the map to scroll the canvas again.

The + and − buttons at the map's bottom left zoom without a click first. Once you zoom, Whole map beside them goes back to the start. Nobody else sees your zoom, and it is not saved.

In edit mode, Keep this view beside them makes the view the map's start. The dashboard saves it like any other edit, and everyone opens the map there.

Distances, areas and points inside regions come from the SQL of a BigQuery datasource: BigQuery's geography functions compute them, and the map draws the result. The SQL of a derived datasource computes no geometry.

Make a scorecard

You build a scorecard on the canvas like a chart. Select one, and its own authoring blocks appear: Data, Fields and Filters in the data bar on its top edge, the Number card at its left with Value, Comparison and Sparkline, and the folded Block card under it with Block size and Code.

1. Add a scorecard from the palette. If the dashboard has several datasources, pick one in the Data block.
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, distinct, last, or first; distinct counts each value once), the number format, and where the status color shows. On a date column, max, min, last and first show one date, such as the latest day in the data.
4. In the Comparison block, turn on Compare for a change line. Previous period, Previous year and Custom range compare the whole selected date range with an earlier one, as a chart does. Periods ago compares the latest group of a period column with an earlier group. Target and Another field compare with a 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 aggregate in SQL, 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 Data block holds the datasource, and the Filters block holds the scorecard's own filters.

Make a table

1. Add a table from the palette. A fresh table shows every column of its datasource. Select the table. Its blocks show around it: the data bar on its top edge, and the Table card on its left. In edit mode, the headers of the table are its fields.
2. In the Table card, pick the kind of table. Rows shows the rows of the datasource. Summary adds up the rows per row field, with one column per value. Pivot also spreads the values across the keys of a column field.
3. To add a field, drag it from the Fields list onto the headers, or select the + after the last header. Where you drop the field decides its role: among the row fields it groups the rows, and among the values it is added up. Each value carries its own reducer, so one table shows a sum beside an average.
4. To change one column, select its header. The column's settings open beside the table: the field, the heading, the format, what the cell shows, and its color rules. To move the column, drag its header, or select Move left or Move right. To remove a field or hide a column, select ✕ on its header.
5. A Pivot shows its column fields and its values in a band over the headers. You can add up to two column fields. A Pivot reads best with one value per cell, because each extra value repeats under every column key.
6. 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.
7. To turn a column's values into links or pictures, open the column's settings and 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.
8. Add color rules in the column's settings. 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.
9. Turn on the totals you need in Totals, in the Table card: 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 popover says so and names the values it affects.
10. To show the change of a Summary's values against an earlier period, open Comparison in the Table card. Turn on Compare with an earlier period, then select the values under Change columns. Each value you select gets a change column after it.
11. To show a value of a Summary as a trend line in each row, open the value's settings, turn on Show as a trend, and pick the date column in Trend over.
12. To show a chart when a reader points at a row, open Chart in tooltip in the Table card and pick a chart of the dashboard. The chart draws filtered to the row. To show that chart only in the tooltip, hide it from viewers (see Arrange the canvas).

Table options holds the sort, the page size, Wrap long text, and Keep first columns in place. On each folded group, you see the names of 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. To resize without a drag, type its Width and Height in canvas pixels in the Block size row of the block's folded Block card. The top-left corner stays in place.
• 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. You get no confirmation before a delete. A notice has the name of the block and the undo key.
• Paint order — where blocks overlap, Bring to front and Send to back in the ⋯ menu reorder them.
• Hide from viewers — select it in the ⋯ menu of a block to show the block to editors only. Edit mode shows the block faded, with a dashed outline and the tag Hidden from viewers. View mode, the published page and the scheduled sends leave it out. Show to viewers in the same menu shows it again. A hidden block is not private: every viewer gets the whole dashboard, with the block in it. A frame leaves the page view with its own setting (see Make pages with frames).
• 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 reads one frame at a time, as one page of a report, and can switch to the whole canvas.

To select a frame, click its name or its border. A click inside the frame selects the block under the pointer. A selected frame shows its settings beside it, in the Frame card.

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 holds no blocks, not even the blocks that it covers.
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 Shape in the Frame card, then select 16:9, 4:3, or A4. 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, open Page list in the Frame card, then select Move earlier or Move later.

To see the pages as a reader sees them:

1. Set the mode switch in the header to View. You see the first page, and each frame is a tab, in page order.
2. 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 its first page (Read a dashboard page by page). If your frames only group parts of one overview, open Dashboard settings, and under Canvas set Opens on to Canvas. A reader on a phone still opens on the pages.

• 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 is smaller there.

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 "olena@example.org 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 on the icon rail.

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 you see a notice 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.

Try a chart before viewers see it

Org installs only

The dashboard saves each edit, so every viewer sees a chart you add at once. To build a chart where only you and the other editors see it, use your sandbox. A sandbox is your own charts over the live dashboard. You need edit access to the dashboard, and sandboxes must be on in Dashboard settings.

1. In the header, select Sandbox in the View | Edit | Sandbox switch. A banner across the top is the sign that you are in your sandbox. The dashboard's own blocks lock.
2. Add a chart, or point at a chart, select ⋯ in its header and select Copy to sandbox. Change the chart as you change any chart.
3. When the chart is ready, select ⋯ in its header and select Add to dashboard. On a copy, select Replace to put it over the chart it came from.

The chart moves to the dashboard, with the derived views it reads, and every viewer sees it. In the sandbox, you can only add charts. To change the dashboard's own blocks, select Edit.

Write and decorate

Notes

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

To draw a diagram, such as a flowchart, a sequence or a timeline, write its Mermaid text in a code block that starts with ```mermaid. The diagram takes the dashboard's colors. A pie chart and the other charts of numbers do not draw: put them in a chart block. When a diagram cannot draw, you see its text as code, with the fix on the line under it. To read the text of a drawn diagram, press Show diagram text under it.

While you write, a format bar sits on the note's top edge. Each button writes the markdown for you: select words and press B to make them bold, or put the caret on a line and pick a heading level or a list. Link and Picture ask for the address. Cmd+B, Cmd+I and Cmd+K (Ctrl on Windows) do bold, italic and a link. To reach the bar from the keyboard, press Alt+F10.

For a long note, press Full view in its Note card. The note fills the screen, with its markdown beside the drawn text.

Shapes

A shape is a bare figure, with no header. To move a shape, drag it from any point on the figure. Its actions show above its top-right corner when you point at it or select it. To write the label, double-click the shape, or select it and press Enter or F2. The label saves as you type, and Escape closes the editor and keeps the 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.

Describe a chart or an image in words

A reader who uses a screen reader cannot see a chart or an image. Write what it shows, and the screen reader reads your words after the block's title. The same text, followed by the generated summary, goes with the chart's picture in a Slack delivery.

1. For a chart, select it and open its Title block. For a sankey, select it and open Description in its folded Block card. For an image, select it and open Description in its Image card.
2. In Text description, write the finding in a sentence or two: "Signups doubled over the quarter, with a dip in the week of the outage."

The field takes up to 1,000 characters, and a count under it shows how many are left. Keep it under 250, because a screen reader reads all of it before the reader can move on. When an image carries no information, such as a divider or a background, select This image is decorative instead, and a screen reader skips it.

On a chart or a sankey, arkush also writes a short summary from the data, such as the largest value or the trend, and a screen reader reads it after your description. The description field shows that summary under it. Read it before you write, and add what the data cannot say: why the numbers moved, or what the reader should do. arkush never puts the summary in the field.

Block titles

To rename a block, double-click its title or press F2. If the title is blank, the block has no title. A blank section or frame has an italic Untitled section or Untitled frame label while you edit, and no label for a viewer. A control with a blank title shows no title, because its widget already shows the label of its param. A shape shows no title. To rename a shape, open Code in its folded Block card and edit title in its JSON. The form of a chart adds the Title choice: in the header, drawn on the chart itself, or hidden. Where you can publish the dashboard, the same place has Show the title on the image link, for the PNG of the published chart (see Put a chart in a message, a README or a slide). On a note, you set the Title row of its Block card to show the title in the header or to hide it. On other block types, you hide a title only in the Source panel. A hidden title is nowhere on the block, not even in its header while you edit.

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.

Put a chart into an article from the chart

1. If the finding needs filters, set them on the canvas. The article keeps the filters that are on screen when you add the chart.
2. Point at the chart, select ⋯ in its header, and select Add to article….
3. If the dashboard has articles, pick one, or select Write a new article, and select Add. If the dashboard has no article, you skip this step: you get a new article named Untitled article.

The chart goes at the end of the article's text. You see a notice with the article's name. Select Open article in the notice to read the article. When the notice is gone, open the article from the Articles panel on the right icon rail.

Keep an article out of the published copy

1. Open the article from the Articles panel, or with Open article.
2. Select Edit in the bar at the top of the article.
3. Under Views, turn on Draft: keep out of the published dashboard.

In the Articles panel and on the article's card on the canvas, the article then has the Draft label. When you select Publish, the dialog has the names of the drafts that stay out. Turn the switch off to publish the article with the dashboard.

Edit the JSON where the form ends

Open the Source panel from the right icon rail, or press ⌘/Ctrl J. In the panel, you see the whole dashboard as JSON. The panel follows the canvas until you type. Your typed edits take effect only when you select 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, select it and open Code in its folded Block card, then select Edit as JSON: the same block as raw JSON, and Apply works the same way. A layered or composite chart has a Settings button in its header instead, and its form has Edit as JSON at its foot.

Edit the spec of a chart

The spec of a chart is its Vega-Lite JSON. You edit it in the code pane of the Chart workspace, a full-window view of one chart. You need edit access to the dashboard. Without it, the code pane reads Read-only and takes no typing. To get edit access, ask the owner of the dashboard.

Leave data, width, height and config out of the spec. The save drops width, height and config, because the canvas sets the size and the theme. A spec with its own data draws that data in place of the rows of its datasource.

Every chart in edit mode opens in the Chart workspace from the ⋯ menu in its block header, the title row at the top of the chart: select Open in Chart workspace. A composite chart has a spec that puts several views together, such as layers, facets, repeats, or side-by-side views. Authoring blocks are the cards of settings around a selected chart. A composite chart has none, so you open it from the ⋯ menu.

An edit that layers a chart beyond labels and reference lines makes it composite, and its authoring blocks close. To get them back, take the edit back with undo.

To open any other chart with the cursor already in the code:

1. Select the chart.
2. At the left of the chart, select the name Chart to unfold the Chart card.
3. Select Code in the Chart card. Its popover opens.
4. In the popover, select Edit spec. The chart opens in the Chart workspace, with the cursor in the code pane at the right.
5. Type your change in the code pane. The chart redraws a moment after you stop typing. After a longer pause, the code pane saves the change to the dashboard, and the save state in the bar at the top changes from Unsaved changes to Saved.
6. To go back to the dashboard, select ‹ Canvas at the left of the bar at the top. A change that is waiting for its save saves as you go.

The code pane saves by itself, and it has no Apply. While the JSON does not parse, nothing saves. You see the chart's last good version, dimmed, and under the chart, a line with the line number and the column of the problem. Correct the JSON in the code pane at that line and column. When it parses again, the chart is no longer dimmed, the line goes, and the change saves.

If you go back to the canvas before you correct it, the text you typed after the last good version is lost. A notice says that the code was not saved, and the chart keeps the last code that parsed. To change it, open the chart in the Chart workspace again.

A change can parse and still draw nothing, for example a misspelled mark type. That change saves, and the chart shows a message that names the problem. In the code pane, ⌘Z (Ctrl Z on Windows) takes back your typing. To take back a change that already saved, go back to the canvas and use undo, or put back an earlier version from Version history.

The code pane completes Vega-Lite 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 code pane 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 code pane 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 (Shift+Option+F on a Mac). A spec that does not parse stays as you typed it.

Above the spec, the code pane 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 marks as JSON-only. For the current list, read What needs the Source panel or an agent.

In the Source panel, you edit 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.