Tile Types Reference

Configuration options and examples for KPI, Chart, Table, and Markdown tiles

This page covers the configuration options and examples for each tile type. For an overview of how tiles work, see Introduction to Tiles.

KPI tiles

KPI tiles display single metrics prominently. They're perfect for key performance indicators that need to stand out at a glance.

When should I use a KPI tile?

Use KPIs when you have a single number that stakeholders check regularly: total revenue, conversion rate, active users, or any metric that answers "how are we doing?"

Configuration options

Example

# KPI showing total revenue collected in last 90 days
engine: "sql"
sql: |
  SELECT SUM(amount) as total_collected
  FROM LAKE.STRIPE.charges
  WHERE status = 'succeeded'
    AND to_timestamp(created) >= CURRENT_DATE - INTERVAL '90 days'

viz:
  type: "kpi"
  series:
    - field: "total_collected"
      format: "currency"         # Display as $X,XXX
  colors:
    color: "#10b981"             # Green

Chart tiles

Chart tiles visualize data graphically. You can choose from line, area, bar, or pie charts depending on what you're trying to show.

Chart types

When should I use a line chart vs a bar chart?

Use a line chart when showing how something changes over time: daily, weekly, or monthly trends. The x-axis is typically a date.

Use a bar chart when comparing discrete categories: regions, products, or segments. The x-axis is typically a category name.

Configuration options

Example

engine: "sql"
sql: |
  SELECT
    DATE_TRUNC('month', created_at) as month,
    SUM(amount) as revenue
  FROM orders
  WHERE created_at >= CURRENT_DATE - INTERVAL '12 months'
  GROUP BY 1
  ORDER BY 1

viz:
  type: "line"                   # Change to "bar", "area", or "pie"
  series:
    - field: "revenue"
      label: "Revenue"
      format: "currency"
  colors:
    palette: "default"           # Or use color: "#3b82f6" for a specific hex
  legend:
    position: "top"              # top, bottom, left, right
  orientation: "vertical"        # Bar charts only: vertical or horizontal

Type-specific options

Table tiles

Table tiles display query results in rows and columns. They're useful when users need to explore detailed data, drill into records, or export information.

When should I use a table tile?

Use tables when:

• Users need to see individual records (e.g., list of customers, recent orders)
• The data has many columns that don't visualize well as a chart
• Users want to filter, sort, or search the data
• You're providing a drill-down from a summary metric

Configuration options

Example

# Top 20 customers by lifetime value
engine: "sql"
sql: |
  SELECT
    customer_name,
    customer_email,
    COUNT(order_id) as total_orders,
    SUM(order_total) as lifetime_value,
    MAX(order_date) as last_order
  FROM orders
  JOIN customers ON orders.customer_id = customers.id
  GROUP BY 1, 2
  ORDER BY lifetime_value DESC
  LIMIT 20

viz:
  type: "table"
  columns:
    - field: "customer_name"
      label: "Customer"
    - field: "total_orders"
      label: "Orders"
    - field: "lifetime_value"
      label: "LTV"
      format: "currency"
    - field: "last_order"
      label: "Last Order"
      format: "date"
  sorting:
    field: "lifetime_value"
    direction: "desc"

Markdown tiles

Markdown tiles add formatted text to your Doc. Use them for section headers, descriptions, methodology notes, or any context that helps viewers understand your dashboard.

When should I use a markdown tile?

Use markdown to:

• Add section headers that organize your dashboard
• Explain methodology or data sources
• Provide context for metrics ("Revenue excludes refunds")
• Add links to related resources

Supported formatting

Example

type: "markdown"
content: |
  # Executive Revenue Dashboard

  Real-time revenue metrics combining Stripe payment data and HubSpot sales pipeline.

  **Data sources**: Stripe charges, HubSpot deals
  **Period**: Last 90 days, updated hourly

  ---

  For questions about this dashboard, contact the Revenue Ops team.

HTML tiles (Data Apps)

HTML tiles render data apps inside your Doc: source-authored React applications compiled to a single HTML file with client-side DuckDB WASM, Perspective.js, and a built-in component library. They go beyond standard tiles with interactive filters, pivot tables, ECharts visualizations, and fully custom layouts.

When should I use an HTML tile?

Use HTML tiles when you need:

• Client-side filtering, drill-down, or brush-selectable date ranges
• Custom visualizations (ECharts, Perspective.js)
• Multi-tab layouts (e.g., Dashboard / Explorer / Report)
• A single full-screen interactive experience
• Rich component library (KPI cards, report tables, multi-selects)

For standard KPIs, charts, and tables, YAML dashboards are faster to build and easier to maintain.

Example

# Full-screen data app
version: 1
schemaVersion: "2025-01"
kind: dashboard
metadata:
  name: "Interactive Sales Explorer"
datasets: {}
layout:
  columns: 36
  tiles:
    - id: app
      x: 0
      y: 0
      w: 36
      h: 22
      type: html
      fullScreen: true
      driveFile: "apps-v2/sales-explorer/dist/index.html"

For the full guide on building data apps, see Data Apps. Scaffold a new app in one command with npx create-definite-app; the framework (@definite-app/data-apps) ships templates, build tooling, runtime, and components.

Next steps