Author Image

CEO & Co-founder of Visivo

Customizable Analytics with Visivo's Code-First Approach

Learn how Visivo's BI-as-code philosophy enables teams to build highly customizable analytics dashboards that adapt to any use case through YAML configuration.

Customizable analytics dashboard configuration

Every team has its own data sources, its own chart requirements and its own workflow, and generic BI tools rarely fit any of them. Forrester research found that between 60% and 73% of enterprise data goes unused for analytics, often because the tool forces teams into templates that do not match what they need. Gartner put the consequence plainly: "Only 20% of analytics insights will deliver business outcomes through 2022."

Visivo takes a code-first approach. Every part of a project lives in YAML under version control, so a team shapes the analytics to the problem instead of the other way around. Here is how that works in practice, from project configuration to deployment, on Visivo's BI-as-code platform.

The power of configuration-driven analytics

Traditional BI tools keep configuration behind a GUI, which makes customization slow and version control impossible. Visivo puts every part of your analytics in readable YAML files. A dashboard stops being a black box and becomes a system you can read, change and review.

We compare the two approaches in YAML vs GUI BI Configuration and show what the code-first side unlocks in Developer-First BI Workflows.

When analytics is code, customization is the default. Need a specific chart type? Configure it. Want your own colors? Define them. Need a complex transformation? Write the SQL. Every part of the pipeline is code you can test and reproduce.

Building custom dashboards with Visivo

Visivo exposes over 40 chart types through Plotly.js, each configurable in YAML, so you are not limited to a fixed set of templates. The rest of this section builds a sales analytics dashboard one piece at a time.

Starting with project configuration

A project starts with a project file that sets defaults for everything in it:

# project.visivo.yml
name: Custom Sales Analytics

defaults:
  source_name: primary_warehouse # defined in the sources block below

theme:
  # Global customization for all charts
  font_family: "Inter, system-ui, sans-serif"
  font_size: 14
  plotly_layout:
    hovermode: x unified
    hoverlabel:
      bgcolor: "#1a1a1a"
      font:
        color: "#ffffff"

The theme sets project-wide defaults. A chart's own layout always wins over the theme, so individual charts can still differ where they need to.

Connecting to your data sources

A project can connect to several sources at once. See Modern Data Stack Alignment for how Visivo fits alongside the rest of your stack:

name: source_example

sources:
  - name: primary_warehouse
    type: snowflake
    account: ${env.SNOWFLAKE_ACCOUNT}
    database: ANALYTICS
    warehouse: COMPUTE_WH
    db_schema: SALES
    username: ${env.SNOWFLAKE_USER}
    password: ${env.SNOWFLAKE_PASSWORD}

  - name: postgres_operational
    type: postgresql
    host: ${env.PG_HOST}
    database: operations
    port: 5432
    username: ${env.PG_USER}
    password: ${env.PG_PASSWORD}

  - name: local_sqlite
    type: sqlite
    database: ./data/reference_data.db

${env.VAR_NAME} keeps credentials out of the file, so the configuration can live in Git. Set the variables in your shell or in a .env file at the project root, and keep that file out of Git. The same mechanism carries into CI, which we cover in CI/CD Analytics Implementation.

Creating custom data models

A model is a SQL query. Write the transformation you need:

name: model_example

models:
  - name: sales_performance
    sql: |
      WITH monthly_metrics AS (
        SELECT
          DATE_TRUNC('month', order_date) as month,
          product_category,
          sales_region,
          SUM(order_value) as revenue,
          COUNT(DISTINCT customer_id) as unique_customers,
          COUNT(*) as order_count,
          AVG(order_value) as avg_order_value,
          PERCENTILE_CONT(0.5) WITHIN GROUP (ORDER BY order_value) as median_order_value
        FROM orders
        WHERE order_status = 'completed'
        GROUP BY 1, 2, 3
      )
      SELECT
        month,
        product_category,
        sales_region,
        revenue,
        unique_customers,
        order_count,
        avg_order_value,
        median_order_value,
        LAG(revenue, 1) OVER (PARTITION BY product_category, sales_region ORDER BY month) as prev_month_revenue,
        revenue - LAG(revenue, 1) OVER (PARTITION BY product_category, sales_region ORDER BY month) as month_over_month_change
      FROM monthly_metrics
      ORDER BY month DESC, revenue DESC

CTEs, window functions and percentiles are hard or impossible to express in a GUI query builder. Here they are plain SQL. For heavier transformation work, see Python Data Pipelines or the dbt™ Integration.

Designing custom visualizations

An Insight exposes every Plotly property, down to the hover template:

insights:
  - name: revenue-trend-by-category
    props:
      type: scatter
      mode: lines+markers
      x: ?{ ${ref(sales_performance).month} }
      y: ?{ ${ref(sales_performance).revenue} }
      name: ?{ ${ref(sales_performance).product_category} }
      line:
        shape: spline
        width: 3
      marker:
        size: 8
        line:
          width: 2
          color: "#ffffff"
      hovertemplate: |
        <b>%{fullData.name}</b><br>
        Month: %{x|%B %Y}<br>
        Revenue: $%{y:,.0f}<br>
        Customers: %{customdata[0]:,.0f}<br>
        MoM Change: $%{customdata[1]:+,.0f}<br>
        <extra></extra>
      customdata:
        - ?{ ${ref(sales_performance).unique_customers} }
        - ?{ ${ref(sales_performance).month_over_month_change} }
    interactions:
      - split: ?{ ${ref(sales_performance).product_category} }

  - name: category-distribution
    props:
      type: pie
      labels: ?{ ${ref(sales_performance).product_category} }
      values: ?{ sum(${ref(sales_performance).revenue}) }
      hole: 0.4
      marker:
        colors:
          - "#3498db"
          - "#e74c3c"
          - "#f39c12"
          - "#2ecc71"
          - "#9b59b6"
      textposition: outside
      textinfo: label+percent
      textfont:
        size: 14

Composing custom chart layouts

A chart combines Insights and gives them a layout:

charts:
  - name: revenue-analysis
    insights:
      - ${ref(revenue-trend-by-category)}
    layout:
      title:
        text: "Revenue Trends by Product Category"
        font:
          size: 24
          family: "Inter, sans-serif"
      xaxis:
        title:
          text: "Month"
        tickformat: "%b %Y"
        showgrid: true
        gridcolor: "#e0e0e0"
      yaxis:
        title:
          text: "Revenue ($)"
        tickformat: "$,.0f"
        showgrid: true
        gridcolor: "#e0e0e0"
      height: 450
      margin:
        l: 80
        r: 40
        t: 80
        b: 60
      paper_bgcolor: "#ffffff"
      plot_bgcolor: "#fafafa"
      colorway:
        - "#3498db"
        - "#e74c3c"
        - "#f39c12"
        - "#2ecc71"
        - "#9b59b6"
      legend:
        orientation: h
        yanchor: bottom
        y: 1.02
        xanchor: right
        x: 1

  - name: category-chart
    insights:
      - ${ref(category-distribution)}

Building interactive dashboards

A dashboard arranges charts, tables and inputs in rows:

name: example_project

dashboards:
  - name: Sales Performance Dashboard
    rows:
      # Header with branding
      - height: compact
        items:
          - markdown:
              content: |
                # Sales Performance Analytics

                This dashboard provides insights into sales performance across product categories and regions.

      # Main visualizations
      - height: large
        items:
          - width: 2
            chart: ${ref(revenue-analysis)}
          - width: 1
            chart: ${ref(category-chart)}

      # Detailed table
      - height: medium
        items:
          - width: 3
            table:
              name: detailed-metrics-table
              data: ${ref(sales_performance)}
              rows_per_page: 25

      # Interactive controls
      - height: small
        items:
          - input: ${ref(date-range-selector)}

inputs:
  - name: date-range-selector
    type: single-select
    options:
      - "Last 30 Days"
      - "Last Quarter"
      - "Year to Date"
      - "All Time"
    display:
      type: dropdown
      default:
        value: "Last Quarter"

Advanced customization techniques

Using inputs for dynamic dashboards

Visivo has no templating language. To let viewers change what a dashboard shows, define an input and use its value in an Insight interaction:

name: example_project

inputs:
  - name: region
    type: single-select
    options: ?{ SELECT DISTINCT sales_region FROM ${ref(sales_performance)} }

insights:
  - name: revenue-by-region
    props:
      type: bar
      x: ?{ ${ref(sales_performance).product_category} }
      y: ?{ sum(${ref(sales_performance).revenue}) }
    interactions:
      - filter: ?{ ${ref(sales_performance).sales_region} = '${ref(region).value}' }

Add the input to a dashboard row with input: ${ref(region)}. The viewer applies the filter in the browser, with no round trip to your database.

Creating reusable components

Split configuration into files that other projects can include:

name: insight_example

# components/kpi-indicators.visivo.yml
models:
  - name: kpi_metrics
    sql: SELECT current_value, previous_value FROM kpi_summary

insights:
  - name: generic_kpi_indicator
    props:
      type: indicator
      mode: number+delta
      value: ?{ ${ref(kpi_metrics).current_value} }[0]
      delta:
        reference: ?{ ${ref(kpi_metrics).previous_value} }[0]
        relative: true
        increasing:
          color: "#2ecc71"
        decreasing:
          color: "#e74c3c"
      number:
        font:
          size: 48
          family: "Inter, sans-serif"
      domain:
        x: [0, 1]
        y: [0, 1]

Then include the file from the main project:

name: visivo_project

includes:
  - path: components/kpi-indicators.visivo.yml

Implementing custom color schemes

Put your organization's palette in the project theme:

name: insight_example

theme:
  colorway:
    - "#1a237e" # Deep blue
    - "#3949ab" # Medium blue
    - "#5e35b1" # Purple
    - "#e91e63" # Pink
    - "#ff6f00" # Orange

Every chart uses these series colors unless its own layout sets different ones.

Testing your custom analytics

Tests live in YAML next to the Insights they check. Each assertion is a Python expression over an Insight's computed values, with numpy available:

name: test_example

tests:
  - name: revenue-is-never-negative
    assertions:
      - ">{ numpy.min( ${ref(revenue-trend-by-category).props.y} ) >= 0 }"

  - name: revenue-trend-has-data
    assertions:
      - ">{ len( ${ref(revenue-trend-by-category).props.x} ) > 0 }"
      - ">{ len( ${ref(revenue-trend-by-category).props.x} ) == len( ${ref(revenue-trend-by-category).props.y} ) }"

Run tests after visivo run and before deployment:

visivo test

We go deeper on what to test, and when, in Test Before Dashboard Deployment.

Deployment and version control

Everything above is text, so it goes in Git. That gives you review, history and rollback, which we cover in Dashboard Version Control Collaboration:

# Initialize version control
git init
git add project.visivo.yml
git add models/*.yml
git add dashboards/*.yml
git commit -m "Initial custom sales analytics configuration"

# Run the queries, then deploy to staging for review
visivo run
visivo deploy -s staging

# After approval, deploy to production
visivo deploy -s production

Getting started with customization

To try this on your own data:

# Install Visivo CLI
pip install visivo

# Initialize a new project
visivo init --project-dir my-custom-analytics --bare

# Start local development
cd my-custom-analytics
visivo serve

To see a finished project first, start from a bundled example. visivo init --example ev-sales creates the dashboard below, with KPI indicators, bar charts and a pie chart on a local DuckDB file.

The bundled EV Sales example dashboard in Visivo, with KPI indicators, bar charts and a pie chart rendered from a local DuckDB file The ev-sales example (visivo init --example ev-sales) served locally by Visivo 2.3.0.

Visit docs.visivo.io for the full reference on every option above, or sign up at app.visivo.io to deploy to Visivo Cloud.

Related reading: Visualizations as Code, BI as Code Scalable Systems, and Lightning-Fast Embedded Dashboards.

Customization should not mean fighting the tool. When the whole project is YAML in Git, changing a color, a query or a layout is an edit and a pull request, and the result is the same on every run.

Install command copied