Skip to main content

Data Table

Examples

Selecting Specific Columns

<DataTable data={query_name} search=true>
<Column id=date />
<Column id=country title="Country Name" />
<Column id=value_usd />
</DataTable>

Displaying All Columns in Query

<DataTable data="{query_name}" search="true" />

Deltas

<DataTable data={countries}>
<Column id=country />
<Column id=category />
<Column id=value_usd />
<Column id=yoy contentType=delta fmt=pct title="Y/Y Chg"/>
</DataTable>

Total Row

<DataTable data={countries} totalRow=true rows=5/>

Default Aggregation Functions

<DataTable data={countries} totalRow=true rows=5>
<Column id=country/>
<Column id=gdp_usd totalAgg=sum/>
<Column id=gdp_growth totalAgg=weightedMean weightCol=gdp_usd fmt='pct2'/>
<Column id=population totalAgg=mean fmt='#,##0"M"'/>
</DataTable>

Custom Aggregations Values

<DataTable data={countries} totalRow=true rows=5>
<Column id=country totalAgg="Just the USA"/>
<Column id=gdp_usd totalAgg={countries[0].gdp_usd} totalFmt=usd/>
</DataTable>

Custom Total Formats

<DataTable data={countries} totalRow=true rows=5>
<Column id=country totalAgg="All Countries"/>
<Column id=continent totalAgg=countDistinct totalFmt='# "Unique continents"'/>
<Column id=gdp_usd totalAgg=sum fmt='$#,##0"B"' totalFmt='$#,##0.0,"T"'/>
<Column id=gdp_growth totalAgg=mean fmt='pct2' totalFmt='pct1'/>
<Column id=interest_rate totalAgg=mean fmt='pct2' totalFmt='pct1'/>
<Column id=inflation_rate totalAgg=mean fmt='pct2' totalFmt='pct1'/>
<Column id=jobless_rate totalAgg=mean fmt='pct0'/>
<Column id=gov_budget totalAgg=mean fmt='0.0"%"'/>
<Column id=debt_to_gdp totalAgg=mean fmt='0"%"'/>
<Column id=current_account totalAgg=mean fmt='0.0"%"'/>
<Column id=population totalAgg=sum fmt='#,##0"M"'/>
</DataTable>

Conditional Formatting

Default (scaleColor=green)

<DataTable data={countries}>
<Column id=country />
<Column id=country_id align=center/>
<Column id=category align=center/>
<Column id=value_usd contentType=colorscale/>
</DataTable>

scaleColor=red

<DataTable data={countries}>
<Column id=country />
<Column id=country_id align=center/>
<Column id=category align=center/>
<Column id=value_usd contentType=colorscale scaleColor=red/>
</DataTable>

scaleColor=blue

<DataTable data={countries}>
<Column id=country />
<Column id=country_id align=center/>
<Column id=category align=center/>
<Column id=value_usd contentType=colorscale scaleColor=blue/>
</DataTable>

Custom Colors

<DataTable data={orders_by_category} rowNumbers=true>
<Column id=month/>
<Column id=category/>
<Column id=sales_usd0k contentType=colorscale scaleColor=#a85ab8 align=center/>
<Column id=num_orders_num0 contentType=colorscale scaleColor=#e3af05 align=center/>
<Column id=aov_usd2 contentType=colorscale scaleColor=#c43957 align=center/>
</DataTable>

Including Images

You can include images by indicating either an absolute path e.g. https://www.example.com/images/image.png or a relative path e.g. /images/image.png. For relative paths, see storing static files in a static folder.

In this example, flag is either an absolute path or a relative path to the image.

<DataTable data={countries}>
<Column id=flag contentType=image height=30px align=center />
<Column id=country />
<Column id=country_id align=center />
<Column id=category />
<Column id=value_usd />
</DataTable>
<DataTable data={countries}>
<Column id=country_url contentType=link linkLabel=country />
<Column id=country_id align=center />
<Column id=category />
<Column id=value_usd />
</DataTable>
<DataTable data={countries}>
<Column id=country />
<Column id=country_id align=center />
<Column id=category />
<Column id=value_usd />
<Column id=country_url contentType=link linkLabel="Details &rarr;" />
</DataTable>

This example includes a column country_url which contains a country name as a search term in Google (e.g., https://google.ca/search?q=canada)

<DataTable data={countries} search=true link=country_url>
<Column id=country />
<Column id=country_id align=center />
<Column id=category />
<Column id=value_usd />
</DataTable>

In this example, the SQL query contains a column with links to parameterized pages in the project. Below is an example of the SQL that could be used to generate such links:

select
category,
'/parameterized-pages/' || category as category_link,
sum(sales) as sales_usd0
from needful_things.orders
group by 1

You can then use the link property of the DataTable to use your link column as a row link (category_link in this example):

<DataTable data={orders} link=category_link />

By default, the link column of your table is hidden. If you would like it to be displayed in the table, you can use showLinkCol=true.

Styling

Row Shading + Row Lines

<DataTable data={countries} rowShading=true />

Row Shading + No Row Lines

<DataTable data={countries} rowShading=true rowLines=false />

No Lines or Shading

<DataTable data={countries} rowLines=false />

Column Alignment

<DataTable data={query_name}>
<Column id=country align=right />
<Column id=country_id align=center />
<Column id=category align=left />
<Column id=value_usd align=left />
</DataTable>

Custom Column Titles

<DataTable data={query_name}>
<Column id=country title="Country Name" />
<Column id=country_id align=center title="ID" />
<Column id=category align=center title="Product Category" />
<Column id=value_usd title="Sales in 2022" />
</DataTable>

Raw Column Names

<DataTable data={query_name} formatColumnTitles=false />

DataTable

Options

NameDescriptionRequired?OptionsDefault
dataQuery name, wrapped in curly bracesYesquery name-
rowsNumber of rows to show in the table before paginating results. Use rows=all to show all rows in the table.-number | all10
totalRowShow a total row at the bottom of the table, defaults to sum of all numeric columns-true | falsefalse
rowNumbersTurns on or off row index numbers-true | falsefalse
rowLinesTurns on or off borders at the bottom of each row-true | falsetrue
rowShadingShades every second row in light grey-true | falsefalse
backgroundColorBackground color of the table-Hex color code | css color name-
sortableEnable sort for each column - click the column title to sort-true | falsetrue
searchAdd a search bar to the top of your table-true | falsefalse
downloadableEnable download data button below the table on hover-true | falsetrue
formatColumnTitlesEnable auto-formatting of column titles. Turn off to show raw SQL column names-true | falsetrue
linkMakes each row of your table a clickable link. Accepts the name of a column containing the link to use for each row in your table-column name-
showLinkColWhether to show the column supplied to the link prop-true | falsefalse
generateMarkdownHelper for writing DataTable syntax with many columns. When set to true, markdown for the DataTable including each Column contained within the query will be generated and displayed below the table. -true | falsefalse
emptySet Sets behaviour for empty datasets. Can throw an error, a warning, or allow empty. When set to 'error', empty datasets will block builds in build:strict. Note this only applies to initial page load - empty datasets caused by input component changes (dropdowns, etc.) are allowed. - error | warn | pass error
emptyMessage Text to display when an empty dataset is received - only applies when emptySet is 'warn' or 'pass', or when the empty dataset is a result of an input component change (dropdowns, etc.). - string No records

Column

Use the Column component to choose specific columns to display in your table, and to apply options to specific columns. If you don't supply any columns to the table, it will display all columns from your query result.

Options

NameDescriptionRequired?OptionsDefault
idColumn id (from SQL query)Yescolumn name-
titleOverride title of column-stringcolumn name (formatted)
alignAlign column text-left | center | rightleft
fmtFormat the values in the column (see available formats)-Excel-style format | built-in format | custom format-
totalAggSpecify an aggregation function to use for the total row. Accepts predefined functions, custom strings or values-sum | mean | weightedMean | median | min | max | count | countDistinct | custom string or valuesum
totalFmtSpecify an override format to use in the total row (see available formats). Custom strings or values are unformatted by default.-Excel-style format | built-in format | custom format-
weightColColumn to use as the weight values for weighted mean aggregation. If not specified, a weight of 1 for each value will be used and the result will be the same as the mean aggregation.-column name-
wrapWrap column text-true | falsefalse
contentTypeLets you specify how to treat the content within a column. See below for contentType-specific options.-link | image | delta | colorscale-

Images

contentType=image

NameDescriptionRequired?OptionsDefault
heightHeight of image in pixels-numberoriginal height of image
widthWidth of image in pixels-numberoriginal width of image
altAlt text for image-column nameName of the image file (excluding the file extension)

contentType=link

NameDescriptionRequired?OptionsDefault
linkLabelText to display for link-column name | stringraw url
openInNewTabWhether to open link in new tab-true | falsefalse

Deltas

contentType=delta

NameDescriptionRequired?OptionsDefault
deltaSymbolWhether to show the up/down delta arrow symbol-true | falsetrue
downIsGoodIf present, negative comparison values appear in green, and positive values appear in red.-true | falsefalse
showValueWhether to show the delta value. Set this to false to show only the delta arrow indicator.-true | falsetrue

Conditional Formatting (Color Scales)

contentType=colorscale

NameDescriptionRequired?OptionsDefault
scaleColorColor to use for the scale-green | blue | red | Hex color code | css color namegreen
colorMinSet a minimum for the scale. Any values below that minimum will appear in the lowest color on the scale-numbermin of column
colorMaxSet a maximum for the scale. Any values above that maximum will appear in the highest color on the scale-numbermax of column