Skip to content
Reeflow
Start Building

Getting Started

This guide will walk you through creating your first interactive dashboard using the Reeflow Embed SDK. You’ll learn how to install the SDK, authenticate, and display your first chart and table.

What you’ll build

Section titled “What you’ll build”

By the end of this tutorial, you’ll have a working dashboard that:

  • Displays a bar chart showing revenue by product
  • Shows a data table with order details
  • Supports light and dark themes
  • Is fully interactive and responsive

Time to complete: 5-10 minutes

Prerequisites

Section titled “Prerequisites”

Before you begin, make sure you have:

  • A Reeflow account with an API key (sign up here)
  • Basic knowledge of HTML and JavaScript
  • A text editor and web browser

Step 1: Set up your project

Section titled “Step 1: Set up your project”

  1. Create a new React component

    Create a file named Dashboard.tsx:

    import { ReeflowProvider } from '@reeflow/react';
    

    function Dashboard() {
      return (
        <>
          <h1>Sales Dashboard</h1>
          {/* We'll add components here */}
        </>
      );
    }
    

    export default Dashboard;

  2. Install the React SDK

    Terminal window
    # npm
    npm install @reeflow/react
    

    # pnpm
    pnpm add @reeflow/react
    

    # yarn
    yarn add @reeflow/react

  3. Add basic styling (optional)

    Create a file named Dashboard.css:

    body {
      font-family: system-ui, -apple-system, sans-serif;
      max-width: 1200px;
      margin: 0 auto;
      padding: 2rem;
      background: #f5f5f5;
    }
    

    h1 {
      color: #333;
      margin-bottom: 2rem;
    }
    

    .dashboard {
      display: grid;
      gap: 2rem;
      grid-template-columns: repeat(auto-fit, minmax(500px, 1fr));
    }

    Then import it in your component:

    import './Dashboard.css';

Step 2: Get your embed token

Section titled “Step 2: Get your embed token”

To use Reeflow components, you need an embed token. There are two ways to get one:

If you have a Reeflow account, create a embed auth token using your API key:

// In your backend (Node.js example)
const response = await fetch('https://api.reeflow-data.com/sessions', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${YOUR_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    user: {
      id: 'user_12345',
    },
    organization: {
      id: 'your-org-id',
    },
    expiration: new Date(Date.now() + 3600000).toISOString(), // 1 hour
  }),
});


const { token } = await response.json();
// Send this token to your frontend

Learn more about embed auth tokens.

Step 3: Add the Provider component

Section titled “Step 3: Add the Provider component”

The Provider component wraps all Reeflow components and manages authentication, theming, and API configuration.

Update your component to include the ReeflowProvider:

import { ReeflowProvider } from '@reeflow/react';
import './Dashboard.css';


function Dashboard() {
  return (
    <>
      <h1>Sales Dashboard</h1>


      <ReeflowProvider authToken="your-embed-token-here" theme="default" themeMode="auto">
        <div className="dashboard">{/* We'll add chart and table here */}</div>
      </ReeflowProvider>
    </>
  );
}


export default Dashboard;

Understanding the props:

  • authToken: Your embed token (or use mock prop for mock mode)
  • theme: Visual theme (default, minimal, corporate, etc.)
  • themeMode: Color scheme (auto, light, or dark)

Step 4: Add your first chart

Section titled “Step 4: Add your first chart”

Let’s add a bar chart showing revenue by product category. Add this inside the <div class="dashboard">:

import { ReeflowBarChart } from '@reeflow/react';


<div className="dashboard">
  <ReeflowBarChart
    title="Revenue by Product Category"
    query={{
      from: 'orders',
      dimensions: ['product_category'],
      measures: [
        {
          column: 'total_amount',
          type: 'sum',
          label: 'Total Revenue',
        },
      ],
      order_by: [
        {
          column: 'total_amount',
          direction: 'desc',
        },
      ],
    }}
  />
</div>;

Understanding the query:

  • from: The data source (table name)
  • dimensions: Categories to group by (product categories)
  • measures: Metrics to calculate (sum of revenue)
  • order_by: Sort by revenue descending

This uses JSONQL, Reeflow’s query language. Learn more in the JSONQL documentation.

Step 5: Add a data table

Section titled “Step 5: Add a data table”

Now let’s add a table showing order details. Add this below the chart:

import { ReeflowTable } from '@reeflow/react';


<ReeflowTable
  title="Recent Orders"
  pageSize={10}
  query={{
    from: 'orders',
    dimensions: ['order_id', 'order_date', 'customer_name', 'product_name', 'status'],
    measures: [
      {
        column: 'total_amount',
        type: 'sum',
        label: 'Amount',
      },
    ],
    order_by: [
      {
        column: 'order_date',
        direction: 'desc',
      },
    ],
    limit: 10,
  }}
/>;

Understanding the table query:

  • dimensions: Columns to display (order ID, date, customer, product, status)
  • measures: Calculated metrics (total amount)
  • order_by: Sort by date (most recent first)
  • limit: Show only 10 most recent orders

Step 6: Test your dashboard

Section titled “Step 6: Test your dashboard”

Run your React application and navigate to the Dashboard component. You should see:

  1. ✅ A bar chart showing revenue by product category
  2. ✅ A data table with order details (date, customer, product, amount, status)
  3. ✅ Both components styled with the default theme
  4. ✅ Interactive features (hover tooltips, clickable elements)

Complete example

Section titled “Complete example”

Here’s the complete React component:

import { ReeflowProvider, ReeflowBarChart, ReeflowTable } from '@reeflow/react';
import './Dashboard.css';


function Dashboard() {
  return (
    <>
      <h1>Sales Dashboard</h1>


      <ReeflowProvider mock theme="default" themeMode="auto">
        <div className="dashboard">
          <ReeflowBarChart
            title="Revenue by Product Category"
            query={{
              from: 'orders',
              dimensions: ['product_category'],
              measures: [
                {
                  column: 'total_amount',
                  type: 'sum',
                  label: 'Total Revenue',
                },
              ],
              order_by: [
                {
                  column: 'total_amount',
                  direction: 'desc',
                },
              ],
            }}
          />


          <ReeflowTable
            title="Recent Orders"
            pageSize={10}
            query={{
              from: 'orders',
              dimensions: ['order_id', 'order_date', 'customer_name', 'product_name', 'status'],
              measures: [
                {
                  column: 'total_amount',
                  type: 'sum',
                  label: 'Amount',
                },
              ],
              order_by: [
                {
                  column: 'order_date',
                  direction: 'desc',
                },
              ],
              limit: 10,
            }}
          />
        </div>
      </ReeflowProvider>
    </>
  );
}


export default Dashboard;

Dashboard.css:

body {
  font-family: system-ui, -apple-system, sans-serif;
  max-width: 1200px;
  margin: 0 auto;
  padding: 2rem;
  background: #f5f5f5;
}


h1 {
  color: #333;
  margin-bottom: 2rem;
}


.dashboard {
  display: grid;
  gap: 2rem;
  grid-template-columns: repeat(auto-fit, minmax(500px, 1fr));
}

Next steps

Section titled “Next steps”

Congratulations! You’ve built your first Reeflow dashboard. Here’s what to explore next:

Learn more about components

Section titled “Learn more about components”
  • Workbook - Display complete embedded workbooks with multiple pages
  • Charts - Bar, line, and pie charts with advanced features
  • Tables - Interactive tables with sorting and pagination
  • Provider - Authentication and configuration options
  • Theming - Customize the look and feel

Explore JSONQL

Section titled “Explore JSONQL”

Integration guides

Section titled “Integration guides”

Add more features

Section titled “Add more features”

Try enhancing your dashboard:

  1. Add more charts - Try line and pie charts
  2. Enable interactivity - Listen to row click events
  3. Add filters - Let users filter data dynamically
  4. Switch themes - Add a theme selector dropdown
  5. Go responsive - Optimize for mobile devices

Troubleshooting

Section titled “Troubleshooting”

Components not rendering

Section titled “Components not rendering”

Problem: Components appear as plain HTML tags

Solution: Make sure the SDK is properly imported:

<script type="module">
  import '@reeflow/core';
</script>

Authentication errors

Section titled “Authentication errors”

Problem: “Invalid token” or “Unauthorized” errors

Solutions:

  • Use mock mode for development
  • Verify your embed token is valid and not expired
  • Check that your API key has the correct permissions

No data displaying

Section titled “No data displaying”

Problem: Components load but show “No data available”

Solutions:

  • Check your JSONQL query syntax
  • Verify the table/field names exist in your data source
  • Look at browser console for error messages
  • Try using mock mode to test with sample data

Styling issues

Section titled “Styling issues”

Problem: Components don’t match your design

Solutions:

  • Use CSS Parts to customize components (see Theming)
  • Try different built-in themes
  • Check for CSS conflicts with your existing styles

Using React?

Section titled “Using React?”

If you’re building a React application, check out the React integration guide for:

  • React-specific hooks for accessing component state
  • Best practices to avoid common pitfalls (like infinite re-renders)
  • TypeScript examples and full type safety

Get help

Section titled “Get help”

Need assistance?