ReportBuilder

App.tsx

import { QuillProvider, ReportBuilder } from "@quillsql/react";

function App() {
  return (
    <QuillProvider
      tenants={[{ tenantField: "customer_id", tenantIds: [2] }]}
      publicKey={process.env.QUILL_PUBLIC_KEY}
    >
      <ReportBuilder initialTableName="transactions" />
    </QuillProvider>
  );
}

Allows non-technical users to build SQL queries using either UI or AI and then edit them on the fly. Once users have constructed a query they like, they can click a button and add that report to their dashboard or export it as a CSV.

Make sure QuillProvider is a parent of the ReportBuilder component.

Examples

Ant Design
Material Design

Ant Design

import { ReportBuilder } from "@quillsql/react";

import {
  AntButton,
  AntDeleteButton,
  AntSecondaryButton,
} from "./ui/ant/Button";
import { AntCard } from "./ui/ant/Card";
import { AntCheckbox } from "./ui/ant/Checkbox";
import {
  AntSelectColumn,
  AntDraggableColumn,
  AntColumnSearchEmptyState,
} from "./ui/ant/Column";
import { AntTextInput } from "./ui/ant/Input";
import {
  AntChartBuilderFormContainer,
  AntChartBuilderInputColumnContainer,
  AntChartBuilderInputRowContainer,
  AntContainer,
  AntErrorMessageComponent,
  AntLoadingComponent,
  AntPivotColumnContainer,
  AntPivotRowContainer,
  AntSidebar,
} from "./ui/ant/Layout";
import { AntModal } from "./ui/ant/Modal";
import {
  AntPopover,
  AntFilterPopover,
  AntSortPopover,
  AntLimitPopover,
} from "./ui/ant/Popover";
import { AntSelect } from "./ui/ant/Select";
import { AntTable } from "./ui/ant/Table";
import { AntTabs } from "./ui/ant/Tabs";
import {
  AntSidebarHeading,
  AntLabel,
  AntHeader,
  AntText,
  AntSubHeader,
} from "./ui/ant/Typography";

export function AntReportBuilder() {
  return (
    <ReportBuilder
      destinationDashboard="Transactions"
      TableComponent={AntTable}
      SidebarComponent={AntSidebar}
      ContainerComponent={AntContainer}
      PopoverComponent={AntPopover}
      CardComponent={AntCard}
      ButtonComponent={AntButton}
      ModalComponent={AntModal}
      SecondaryButtonComponent={AntSecondaryButton}
      TextInputComponent={AntTextInput}
      SelectComponent={AntSelect}
      TabsComponent={AntTabs}
      CheckboxComponent={AntCheckbox}
      SelectColumnComponent={AntSelectColumn}
      DraggableColumnComponent={AntDraggableColumn}
      SidebarHeadingComponent={AntSidebarHeading}
      FilterPopoverComponent={AntFilterPopover}
      SortPopoverComponent={AntSortPopover}
      LimitPopoverComponent={AntLimitPopover}
      LabelComponent={AntLabel}
      HeaderComponent={AntHeader}
      SubHeaderComponent={AntSubHeader}
      TextComponent={AntText}
      DeleteButtonComponent={AntDeleteButton}
      ErrorMessageComponent={AntErrorMessageComponent}
      ChartBuilderInputRowContainer={AntChartBuilderInputRowContainer}
      ChartBuilderInputColumnContainer={AntChartBuilderInputColumnContainer}
      PivotRowContainer={AntPivotRowContainer}
      PivotColumnContainer={AntPivotColumnContainer}
      LoadingComponent={AntLoadingComponent}
      ColumnSearchEmptyState={AntColumnSearchEmptyState}
      ChartBuilderFormContainer={AntChartBuilderFormContainer}
    />
  );
}

Material Design

import { ReportBuilder } from "@quillsql/react";

import {
  MaterialButton,
  MaterialDeleteButton,
  MaterialSecondaryButton,
} from "./ui/material/Button";
import { MaterialCard } from "./ui/material/Card";
import { MaterialCheckbox } from "./ui/material/Checkbox";
import {
  MaterialSelectColumn,
  MaterialDraggableColumn,
  MaterialColumnSearchEmptyState,
} from "./ui/material/Column";
import { MaterialTextInput } from "./ui/material/Input";
import {
  MaterialChartBuilderFormContainer,
  MaterialChartBuilderInputColumnContainer,
  MaterialChartBuilderInputRowContainer,
  MaterialContainer,
  MaterialErrorMessageComponent,
  MaterialPivotColumnContainer,
  MaterialPivotRowContainer,
  MaterialSidebar,
} from "./ui/material/Layout";
import { MaterialModal } from "./ui/material/Modal";
import {
  MaterialPopover,
  MaterialFilterPopover,
  MaterialSortPopover,
  MaterialLimitPopover,
} from "./ui/material/Popover";
import { MaterialSelect } from "./ui/material/Select";
import { MaterialTable } from "./ui/material/Table";
import { MaterialTabs } from "./ui/material/Tabs";
import {
  MaterialSidebarHeading,
  MaterialLabel,
  MaterialHeader,
  MaterialText,
  MaterialSubHeader,
} from "./ui/material/Typography";

export function MaterialReportBuilder() {
  return (
    <ReportBuilder
      destinationDashboard="Transactions"
      TableComponent={MaterialTable}
      SidebarComponent={MaterialSidebar}
      ContainerComponent={MaterialContainer}
      PopoverComponent={MaterialPopover}
      CardComponent={MaterialCard}
      ButtonComponent={MaterialButton}
      ModalComponent={MaterialModal}
      SecondaryButtonComponent={MaterialSecondaryButton}
      TextInputComponent={MaterialTextInput}
      SelectComponent={MaterialSelect}
      TabsComponent={MaterialTabs}
      CheckboxComponent={MaterialCheckbox}
      SelectColumnComponent={MaterialSelectColumn}
      DraggableColumnComponent={MaterialDraggableColumn}
      SidebarHeadingComponent={MaterialSidebarHeading}
      FilterPopoverComponent={MaterialFilterPopover}
      SortPopoverComponent={MaterialSortPopover}
      LimitPopoverComponent={MaterialLimitPopover}
      LabelComponent={MaterialLabel}
      HeaderComponent={MaterialHeader}
      SubHeaderComponent={MaterialSubHeader}
      TextComponent={MaterialText}
      DeleteButtonComponent={MaterialDeleteButton}
      ErrorMessageComponent={MaterialErrorMessageComponent}
      ChartBuilderInputRowContainer={MaterialChartBuilderInputRowContainer}
      ChartBuilderInputColumnContainer={
        MaterialChartBuilderInputColumnContainer
      }
      PivotRowContainer={MaterialPivotRowContainer}
      PivotColumnContainer={MaterialPivotColumnContainer}
      ColumnSearchEmptyState={MaterialColumnSearchEmptyState}
      ChartBuilderFormContainer={MaterialChartBuilderFormContainer}
    />
  );
}

Prefetch data from a particular table

You can pass an initialTableName to have the report builder automatically load data from a particular table in your schema.

App.tsx

import { QuillProvider, ReportBuilder } from "@quillsql/react";

function App() {
  return (
    <QuillProvider
      tenants={[{ tenantField: "customer_id", tenantIds: [2] }]}
      publicKey={process.env.QUILL_PUBLIC_KEY}
    >
      <ReportBuilder initialTableName="transactions" />
    </QuillProvider>
  );
}

Edit an existing report

You can pass a reportId to have the report builder load the metadata for a pre-existing report. This might be useful if you want to allow your end users to edit the reports they created.

App.tsx

import { QuillProvider, ReportBuilder } from "@quillsql/react";

function App() {
  return (
    <QuillProvider
      tenants={[{ tenantField: "customer_id", tenantIds: [2] }]}
      publicKey={process.env.QUILL_PUBLIC_KEY}
    >
      <ReportBuilder reportId="664283fb4db8ad000bfe54d7" />
    </QuillProvider>
  );
}

Query all views in your Quill schema

By default, the Quill Report Builder will query all tables in your schema and new reports will be created upon completion.

App.tsx

import { QuillProvider, ReportBuilder } from "@quillsql/react";

function App() {
  return (
    <QuillProvider
      tenants={[{ tenantField: "customer_id", tenantIds: [2] }]}
      publicKey={process.env.QUILL_PUBLIC_KEY}
    >
      <ReportBuilder />
    </QuillProvider>
  );
}

Props

string

The default table name to show when first loading the ReportBuilder.

See the prefetch data example to see an example of how this is used.

string

Sets the dashboard of a report created in the report builder.

Checkout our UI examples to see how this is used.

string

Sets the dashboard section of a report created in the report builder.

Checkout our UI examples to see how this is used.

(props: ButtonComponentProps) => JSX.Element

A primary button component.

Show props

Example

export function ButtonComponent({ onClick, label, disabled, icon }) {
	return (
		<button onClick={onClick} disabled={disabled}>
			{icon}
			{label}
		</button>
	);
}

object

Hide properties

() => void

required

A callback fired when the button is clicked.

string

required

The text content of the button.

boolean

Whether the button is disabled.

ReactNode

An icon to put in front of the label.

(props: ButtonComponentProps) => JSX.Element

A secondary button component.

Show props

Example

export function SecondaryButtonComponent({ onClick, label, disabled, icon }) {
	return (
		<button onClick={onClick} disabled={disabled}>
			{icon}
			{label}
		</button>
	);
}

object

Hide properties

() => void

required

A callback fired when the button is clicked.

string

required

The text content of the button.

boolean

Whether the button is disabled.

ReactNode

An icon to put in front of the label.

(props: DeleteButtonComponentProps) => JSX.Element

A small delete button used to click out of things. Usually an “X” icon.

Show props

Example

import { deleteSVG } from "./ui/icons";
export function DeleteButtonComponent({ onClick }) {
	return <button onClick={onClick}>{deleteSVG}</button>;
}

object

Hide properties

() => void

required

A callback fired when the button is clicked.

(props: TextInputComponentProps) => JSX.Element

A input element for getting text from the user.

Show props

Example

export function TextInputComponent({ id, width, value, label, placeholder, onChange }) {
	return (
		<label>
			{label}
			<input
				id={id}
				style={{ width }}
				value={value}
				placeholder={placeholder}
				onChange={onChange}
			/>
		</label>
	);
}

object

Hide properties

string

required

The id of the input element.

number

required

The width of the input element in pixels.

string

required

The width of the input element in pixels.

string

The label of the text input component.

string

The placeholder for the input element.

(event: ChangeEvent<HTMLInputElement>) => void

required

An event callback that is fired when the input value changes.

A modal component.

Show props

Example

import { Modal } from "./ui/modal";
export function ModalComponent({ isOpen, setIsOpen, title, children, width, height }) {
	return (
		<Modal
			isOpen={isOpen}
			setIsOpen={setIsOpen}
			title={title}
			style={{ width, height }}
		>
			{children}
		</Modal>
	);
}

Hide properties

boolean

required

Whether the modal is open.

(isOpen: boolean) => void

required

A callback to set whether the modal is open.

string

The title of the modal, if any.

ReactNode

required

The body of the modal.

number

The width of the modal, in pixels.

number

The height of the modal, in pixels.

A modal component.

Show props

Example

import { Modal } from "./ui/modal";
export function ChartBuilderModalComponent({ isOpen, setIsOpen, title, children, width, height }) {
	return (
		<Modal
			isOpen={isOpen}
			setIsOpen={setIsOpen}
			title={title}
			style={{ width, height }}
		>
			{children}
		</Modal>
	);
}

Hide properties

boolean

required

Whether the modal is open.

(isOpen: boolean) => void

required

A callback to set whether the modal is open.

string

The title of the modal, if any.

ReactNode

required

The body of the modal.

number

The width of the modal, in pixels.

number

The height of the modal, in pixels.

(props: SelectComponentProps) => JSX.Element

A select component.

Show props

Example

export function SelectComponent({ value, label, width, onChange, options }) {
	return (
		<label>
			{label}
			<select value={value} onChange={onChange} style={{ width }}>
				{options.map(({ value, label }) => <option value={value}>{label}</option>)}
			</select>
		</label>
	);
}

object

Hide properties

string

required

The value of the select element.

string

The label above the select element.

number

required

The width of the select element, in pixels.

(event: ChangeEvent<HTMLSelectElement>) => void

required

An event callback that is fired when the select value changes.

{ value: string; label: string; }[]

required

An array of value, label pairs which represent the select options.

(props: TableComponentProps) => JSX.Element

A table component.

Show props

Example

import { Table } from "./ui/table";
import { LoadingSkeleton } from "./ui/loading";

export function TableComponent({ rows, columns, isLoading }) {
	if (isLoading) return <LoadingSkeleton />
	return <Table rows={rows} columns={columns} />;
}

object

Hide properties

{ [key: string]: any }[]

required

The rows of the table are an array of objects.

{ label: string; field: string; }[]

required

The columns of the table are an array of label, field pairs.

boolean

Whether the table is loading.

A popover component.

Show props

Example

import { Popover } from "./ui/popover";

export function PopoverComponent({ isOpen, setIsOpen, popoverTitle, popoverChildren }) {
	return (
		<Popover isOpen={isOpen} setIsOpen={setIsOpen} title={popoverTitle}>
			{popoverChildren}
		</Popover>
	);
}

Hide properties

boolean

required

Whether the popover is open.

(isOpen: boolean) => void

required

A callback to set whether the popover is open.

string

The label of the popover trigger, if any.

The title of the popover, if any.

The body of the popover.

A popover component for filters created in the report builder.

Show props

Example

import { Popover } from "./ui/popover";

export function FilterPopoverComponent({ isOpen, setIsOpen, popoverTitle, popoverChildren }) {
	return (
		<Popover isOpen={isOpen} setIsOpen={setIsOpen} title={popoverTitle}>
			{popoverChildren}
		</Popover>
	);
}

Hide properties

boolean

required

Whether the popover is open.

(isOpen: boolean) => void

required

A callback to set whether the popover is open.

The title of the popover, if any.

The body of the popover.

string

required

The text contents of the filter item.

(event: MouseEvent<HTMLElement>) => void

required

An event callback fired when the user clicks the delete button on the filter.

A popover component for sort items created in the report builder.

Show props

Example

import { Popover } from "./ui/popover";

export function SortPopoverComponent({ isOpen, setIsOpen, popoverTitle, popoverChildren }) {
	return (
		<Popover isOpen={isOpen} setIsOpen={setIsOpen} title={popoverTitle}>
			{popoverChildren}
		</Popover>
	);
}

Hide properties

boolean

required

Whether the popover is open.

(isOpen: boolean) => void

required

A callback to set whether the popover is open.

The title of the popover, if any.

The body of the popover.

string

required

The text contents of the sort item.

(event: MouseEvent<HTMLElement>) => void

required

An event callback fired when the user clicks the delete button on the sort item.

A popover component for limits created in the report builder.

Show props

Example

import { Popover } from "./ui/popover";

export function LimitPopoverComponent({ isOpen, setIsOpen, popoverTitle, popoverChildren }) {
	return (
		<Popover isOpen={isOpen} setIsOpen={setIsOpen} title={popoverTitle}>
			{popoverChildren}
		</Popover>
	);
}

Hide properties

boolean

required

Whether the popover is open.

(isOpen: boolean) => void

required

A callback to set whether the popover is open.

The title of the popover, if any.

The body of the popover.

string

required

The text contents of the limit.

(event: MouseEvent<HTMLElement>) => void

required

An event callback fired when the user clicks the delete button on the limit.

(props: TabsComponentProps) => JSX.Element

A small navigation menu used to switch between two or more states.

Show props

Example

import { Tabs, Tab } from "./ui/tabs";
export function TabsComponent({ value, onChange, options }) {
	return (
		<Tabs value={value} onChange={onChange}>
			{options.map(({ value, label }) => <Tab value={value}>{label}</Tab>)}
		</Tabs>
	);
}

object

Hide properties

string

required

The value of the currently selected tab.

(event: ChangeEvent<HTMLSelectElement>) => void

required

An event callback fired when the selected tab changes.

{ label: string; value: string; }[]

required

An array of value, label pairs which represent the tabs to display.

(props: CheckboxComponentProps) => JSX.Element

A checkbox component.

Show props

Example

export function CheckboxComponent({ isChecked, label, onChange }) {
	return (
		<label>
			<input type="checkbox" checked={isChecked} onChange={onChange} />
			{label}
		</label>
	);
}

object

Show properties

boolean

required

Whether the checkbox is checked.

string

required

A label for the checkbox component.

(event: React.ChangeEvent<HTMLInputElement>) => void

required

An event callback fired when the checkbox’s value changes.

(props: SidebarComponentProps) => JSX.Element

A container for the left sidebar.

Show props

Example

export function SidebarComponent({ children }) {
	const style = {
		display: "flex",
		flexDirection: "column",
		gap: 24,
	}
	return <aside style={style}>{children}</aside>
}

object

Show properties

ReactNode

required

The children of the sidebar container.

(props: ContainerComponentProps) => JSX.Element

A container for the main content (everything right of the sidebar).

Show props

Example

export function ContainerComponent({ children }) {
	const style = {
		display: "flex",
		flexDirection: "column",
		gap: 24,
	}
	return <main style={style}>{children}</main>
}

object

Hide properties

ReactNode

required

The children of the main container.

() => JSX.Element

A component to show while the query results are loading.

(props: SelectColumnComponentProps) => JSX.Element

A component to show selected columns.

Show props

Example

export function SelectColumnComponent({ label, isSelected, setSelected, DragHandle }) {
	return (
		<div>
			<DragHandle/>
			<input type="checkbox" isChecked={isSelected} onClick={setSelected} />
			{label}
		</div>
	);
}

object

Hide properties

string

required

The label of the selected column.

boolean

required

Whether this column has been selected.

() => void

required

A callback that is fired when the user checks this columns’ checkbox.

({ dragIcon }: { dragIcon: () => JSX.Element }) => JSX.Element

The handle the user drags this column by.

(props: DraggableColumnComponentProps) => JSX.Element

A draggable component used to reorder columns.

Show props

Example

import { DeleteSVG } from "./ui/icons";
export function DraggableColumnComponent({ label, onDelete, DragHandle }) {
	return (
		<div>
			<DragHandle/>
			{label}
			<button onClick={onDelete}>
				<DeleteSVG />
			</button>
		</div>
	);
}

object

Show properties

string

required

The label of the draggable column.

() => void

required

A callback that is fired when this column is removed from the query.

({ dragIcon }: { dragIcon: () => JSX.Element }) => JSX.Element

The handle the user drags this column by.

(props: SidebarHeadingComponentProps) => JSX.Element

A heading element for the sidebar.

Show props

Example

export function SidebarHeadingComponent({ label }) {
	return <h2>{label}</h2>;
}

object

Hide properties

string

required

The text content of the sidebar heading.

(props: CardComponentProps) => JSX.Element

A card component used as a dismissable container of pivot information.

Show props

Example

import { Card } from "./ui/card";
export function CardComponent({ onClick, onDelete, children }) {
	const style = { position: 'absolute', top: 0, right: 0 };
	return (
		<Card onClick={onClick} style={{ position: 'relative' }}>
			{onDelete && <DeleteButton style={style} onClick={onDelete} />}
			{children}
		</Card>
	);
}

object

Hide properties

ReactNode

required

The children of the container.

() => void

A callback that is fired when the card is clicked.

() => void

A callback that is fired the card is deleted.

(props: LabelComponentProps) => JSX.Element

A label component.

Show props

Example

export function LabelComponent({ label }) {
	return <h4>{label}</h4>;
}

object

Hide properties

string

required

The text content of the element.

(props: HeaderComponentProps) => JSX.Element

A header component.

Show props

Example

export function HeaderComponent({ label }) {
	return <h2>{label}</h2>;
}

object

Hide properties

string

required

The text content of the element.

(props: TextComponentProps) => JSX.Element

A simple text component.

Show props

Example

export function TextComponent({ label }) {
	return <p>{label}</p>;
}

object

Hide properties

string

required

The text content of the element.

(props: { label: string }) => JSX.Element

A sub-header component describes a group of inputs.

Show props

Example

export function SubHeaderComponent({ label }) {
	return <h3>{label}</h3>;
}

object

Hide properties

() => void

required

The label of the sub-header component.

(props: { children: ReactNode }) => JSX.Element

A container for each row of inputs for the ChartBuilder form.

Show props

Example

export function ChartBuilderInputRowContainer({ children }) {
	const style = {
		display: "flex",
		flexDirection: "row",
		gap: 12,
	}
	return <div style={style}>{children}</div>
}

object

Show properties

ReactNode

required

The children of the container.

(props: { children: ReactNode }) => JSX.Element

A container for vertically-stacked rows of inputs for the ChartBuilder form.

Show props

Example

export function ChartBuilderInputColumnContainer({ children }) {
	const style = {
		display: "flex",
		flexDirection: "column",
		gap: 12,
	}
	return <div style={style}>{children}</div>
}

object

Show properties

ReactNode

required

The children of the container.

(props: { children: ReactNode }) => JSX.Element

A container for each row of inputs for the pivot form.

Show props

Example

export function PivotRowContainer({ children }) {
	const style = {
		display: "flex",
		flexDirection: "row",
		gap: 12,
	}
	return <div style={style}>{children}</div>
}

object

Show properties

ReactNode

required

The children of the container.

(props: { children: ReactNode }) => JSX.Element

A container for vertically-stacked rows of inputs for the pivot form.

Show props

Example

export function PivotColumnContainer({ children }) {
	const style = {
		display: "flex",
		flexDirection: "column",
		gap: 12,
	}
	return <div style={style}>{children}</div>
}

object

Show properties

ReactNode

required

The children of the container.

(props: { children: ReactNode }) => JSX.Element

A container for vertically-stacked sections of the chart builder form.

Show props

Example

export function ChartBuilderFormContainer({ children }) {
	const style = {
		display: "flex",
		flexDirection: "column",
		gap: 18,
	}
	return <div style={style}>{children}</div>
}

object

Hide properties

ReactNode

required

The children of the container.

(props: { children: ReactNode }) => JSX.Element

A component that displays error messages.

Show props

Example

export function ErrorMessageComponent({ errorMessage }) {
	return <div>{errorMessage}</div>
}

object

Hide properties

ReactNode

required

The error message.

() => JSX.Element

A component to show when no columns match the user’s query.

boolean

default:false

Whether the ReportBuilder is in admin mode (default: false).

boolean

default:true

Whether the ReportBuilder’s AI features are enabled (default: true).

boolean

Whether the PivotModal’s AI features are enabled.

boolean

Whether to show the table format options on the ChartBuilder form.

CSSProperties

Applies the following classes to the ReportBuilder.This can be useful for TailwindCSS-style classname strings.

CSSProperties

Custom styling properties for the ReportBuilder’s top-level container.

string

A report id that the Report Builder will query from and modify.

See the report id example to see an example of how this is used.

(report: QuillReport) => void

A callback function that will trigger when a new report is created.

(report: QuillReport) => void

A callback function that will trigger when a existing report is edited.

boolean

default:true

Whether to hide the copy SQL button.

boolean

default:true

Whether the chart builder is in horizontal view mode.Horizontal view mode is where the chart and table are displayed on the left and the editing form is displayed on the right, rather than being stacked vertically.

Getting Started

Use cases

Components

Hooks

Functions

Reference

ReportBuilder

Examples

Prefetch data from a particular table

Edit an existing report

Query all views in your Quill schema

Props

​Examples

​Prefetch data from a particular table

​Edit an existing report

​Query all views in your Quill schema

​Props

Examples

Prefetch data from a particular table

Edit an existing report

Query all views in your Quill schema

Props