evidence/sites/docs/pages/+layout.svelte --- --- evidence/sites/docs/pages/index.md --- --- sidebar_position: 1 title: What is Evidence? | Evidence Docs description: Evidence is an open source framework for building data products with SQL - things like reports, decision-support tools, and customer-facing/embedded reporting. It's a code-driven alternative to drag-and-drop BI tools. hide_title: true og: image: /img/how-it-works.png --- # What is Evidence? Evidence is an open source framework for building data products with SQL - things like reports, decision-support tools, and embedded dashboards. It's a code-driven alternative to drag-and-drop BI tools. This docs site is an Evidence app. Install Evidence with the [VSCode Extension](vscode:extension/Evidence.evidence-vscode), or see other [installation options](/install-evidence). ## How does Evidence work?

Evidence renders a BI website from markdown files: 1. [Data sources](/core-concepts/data-sources) can include data warehouses, flat files and non-SQL data sources 1. [SQL statements](/core-concepts/queries) inside markdown files run queries against data sources 1. [Charts and components](/core-concepts/components) are rendered using these query results 1. [Templated pages](/core-concepts/templated-pages) generate many pages from a single markdown template 1. [Loops](/core-concepts/loops) and [If / Else](/core-concepts/if-else) statements allow control of what is displayed to users ## Pre-requisites To use Evidence you need to know SQL. A knowledge of [basic markdown syntax](/reference/markdown) is also helpful. ## Getting help If you're trying out Evidence, and need some support we'd love to hear from you. - Message us on Slack - Open an issue on Github - See all the charts and components. If there's **anything** you find difficult in the docs, please [open an issue](https://github.com/evidence-dev/evidence/issues/new/choose) or reach out to us on Slack. --- evidence/sites/docs/pages/guides/index.md --- --- sidebar_position: 6 sidebar_link: false --- --- evidence/sites/docs/pages/guides/system-requirements/index.md --- --- title: System Requirements sidebar_position: 5 description: Evidence requires Node.js, NPM, and Git --- Evidence requires Node.js ≥18.13, 20 or 22, and NPM 7 or above. Check your versions with `node -v` and `npm -v` **Note:** if you are installing NodeJS for the first time, be sure to install the LTS version. Download Node.js + NPM (LTS version) ### Updating Update to the latest npm version with `npm install -g npm@latest` ## Git Evidence requires git. If you do not already have git installed, you can follow the [instructions here.](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) We also recommend signing up for [GitHub](https://github.com) --- evidence/sites/docs/pages/guides/chart-cheat-sheet/index.md --- --- title: Chart Cheat Sheet sidebar_position: 3 description: A quick reference to the elements of an Evidence Chart. --- ## Chart Elements ![chart-elements-one](/img/chart-elements-one.png) #### Horizontal Chart (`swapXY=true`) ![chart-elements-two](/img/chart-elements-two.png) --- evidence/sites/docs/pages/guides/troubleshooting/index.md --- --- title: Troubleshooting sidebar_position: 2 description: Join the Evidence Slack Community for troubleshooting and support --- **Running into Problems?** - Join the [Evidence Community](https://slack.evidence.dev) to get help with issues and discuss feature ideas. - Check out the list of [open issues in our GitHub Repo](https://github.com/evidence-dev/evidence/issues) - If you have a specific question and cannot go through Slack or GitHub, please email ## Checking Version Numbers ```sql commands select 'npm view @evidence-dev/evidence version' as "Command", 'Check Evidence version' as "Description" UNION ALL select 'node -v' as "Command", 'Check NodeJS version' as "Description" ``` Run these commands in your terminal to see which versions your app is using # Common Issues ## Installation ### Not able to run `npm install` This is often related to the version of NodeJS your app is using. See [system requirements](/guides/system-requirements) for more information ### Installation taking a long time On Windows, the initial installation can take up to a few minutes. If it has been longer than 10 minutes and your app hasn't started, [reach out in the Slack community for help](https://slack.evidence.dev) ## Data Sources ### Data is not available for querying Ensure that you've done the following: - Add `.sql` files to your `sources/my-source` directory to define which data to bring into Evidence (does not apply to the CSV connector, which does not require `.sql` files) - Run `npm run sources` to load the data To check whether your data has been successfully loaded into your app, go to the `/explore/schema` page to see which data is in your app. ### Failure in `npm run sources` If you're having problems loading data with `npm run sources`, try using `npm run sources -- --debug` to display additional logs ## Page Loading If you are running into a problem on your page, but are not seeing a clear error message, try looking in your browser console to see if there is additional information available. To open your browser console: - Right click anywhere on your page - Click "Inspect" - the browser dev tools pane should open - Click the "Console" tab - this will display warnings and errors generated by your page This is helpful information to provide when asking questions in slack or creating issues on Github. ## Deployment If you have issues when building or deploying your app, try running `npm run build` locally to see if the behaviour is the same as in your deployment environment. If the build works locally, but not in your deployment environment, check that the NodeJS version used in your deployment environment fits within the [system requirements](/guides/system-requirements). # Known Issues See [our open Github issues](https://github.com/evidence-dev/evidence/issues) for a full list of known issues --- evidence/sites/docs/pages/guides/usql-migration-guide/index.md --- --- title: Universal SQL Migration Guide sidebar_position: 3 description: Migrate your < v24 Evidence app to Universal SQL (v24+) --- Universal SQL is Evidence's latest release, and fundamentally changes how Evidence queries data in order to bring support for three big new features: 1. **Multiple Data Sources:** Combine data from multiple databases, flat files like CSVs, and even non-SQL data sources like Google Sheets - and query them all with SQL 2. **Inputs and Filters:** Use input components to dynamically update your queries and charts based on user input. Filter data using parameterized queries rather than Javascript filter syntax 3. **Adapter Plugins:** Create your own adapter to enable connecting to any data source This is a big release and contains several breaking changes. This guide will help you migrate your existing apps to USQL. The following sections explain what is changing in Evidence with Universal SQL. To jump straight to the migration steps, [click here](#migration-steps). ## Do I need to migrate my app? - If your `@evidence-dev/evidence` package version is `< v24` then it has not yet been migrated, and we encourage you to do so as soon as is practical - `v23` will continue to be supported for now (sunset date TBC) and will receive critical bugfixes during this period - If you're unsure what you need to do, or if you need help, [reach out to us on Slack](https://slack.evidence.dev) in the `#migration` channel ## Breaking Changes - Existing data source connections will need to be reconfigured - Queries to your data source will need to be moved to the new `sources` directory (details below) - Queries in markdown files and in the `queries` directory are now written in DuckDB SQL - Deprecated syntax: - `{data.my_query}`. Use `{my_query}` instead - Declaring variables from queries in `<script>` tags using `let my_var = ` or `var my_var = `. Use `$: my_var` instead ## How Universal SQL Works - Universal SQL introduces a new data loading step (called `run sources`) - you write queries against multiple data sources, and Evidence will combine them all into the same format so you can query across them using SQL - Once your sources are loaded, they can be queried using DuckDB SQL syntax, either directly on your markdown page, or by writing a `.sql` file in your `queries` directory and referencing it in the frontmatter of your markdown file - These DuckDB SQL queries run in your browser and can be changed on the fly by interactive user input (e.g., filters, dropdowns) using parameterized queries (e.g., `where customer_id = '${inputs.customer}'`) ## Change to Project Structure To support multiple data sources, USQL introduces a new `sources` directory, which contains one folder per data source. Each data source folder includes connection configuration files (defined in YAML, but configurable via the settings UI of your project in your browser). If you already have a `sources` directory in your project (e.g., for `.sql` files or `.csv` files), it will need to be renamed to `queries`. This functions in the same way as before, but the `.sql` files use DuckDB SQL syntax and the queries run in the browser rather than during the build step. Queries in your markdown files will use DuckDB SQL syntax and will also run in the browser. #### Pre-USQL Basic Project Structure ```bash +-- .evidence +-- pages/ | `-- index.md +-- sources/ | `-- a_query.sql | `-- another_query.sql ``` #### USQL Basic Project Structure ```bash +-- .evidence +-- pages/ | `-- index.md +-- queries/ | `-- a_query.sql | `-- another_query.sql +-- sources/ | `-- my_source/ | `-- connection.yaml | `-- connection.options.yaml | `-- source_query.sql ``` Optional folders for `components`, `static`, and `partials` still work as they did before. ## Overview of Changes you will need to make **Recommendations** We recommend creating a backup of your project before starting the migration. - Use new template project scaffold - Migrate queries to new project folder structure - Update on-page queries to use DuckDB syntax - (Suggested) Refactor `.filter()` statements to take advantage of SQL-based filtering - (If necessary) Update deprecated syntax - (If necessary) Reinstall any custom plugins - (If necessary) Reinstall any custom external dependencies (non-evidence libraries) - (If necessary) Update `.gitignore` to include `**/connection.options.yaml` - only needed if you do not start from a fresh Universal SQL template ## Migration Steps **VS Code Migration Command** We have created a VSCode extension command to assist with migration. This will aid significantly with the migration process. Steps for VS Code are shown here. If you prefer to complete the steps manually, see the next section below. ### Using the VS Code Migration Command This migration command covers most situations, but there may be edge cases where you will need to make adjustments or fix query syntax. **Troubleshooting** Issues and errors in the migration command can be related to npm or NodeJS versions - if in doubt, update to the latest LTS versions (see [system requirements](/guides/system-requirements)) 1. Ensure you have the Evidence VS Code extension version `1.4.1` or higher installed 2. Open the Evidence project you want to migrate. If your project is within a monorepo, for this migration open only the Evidence project folder as the "workspace" in VS Code - otherwise the migration command will not be able to run 3. Open the command palette (`Cmd`/`Ctrl` + `Shift` + `P`) 4. Type `Evidence: Migrate Project to USQL` and select that command 5. Follow the prompts in VS Code. You will be asked to provide a name for your data source. This will appear as a folder within the `sources` directory in your project (e.g., you could use `needful_things` if using the Evidence demo database) 6. The command should run quickly - no more than a few minutes. If it's taking longer, try cancelling and starting again or [reach out on Slack in the #migration channel for assistance](https://slack.evidence.dev). When the command has finished running, you will have a migrated project. 7. Click `Start Evidence` to run the server, or use the commands below: ```shell npm install npm run sources npm run dev ``` **Notes:** - `npm run sources` is a new step introduced by USQL. This step runs the queries against your data sources and loads the data into Evidence - It is normal to see errors in your terminal at this stage - you need to configure your data source to avoid these (see next step) 8. Configure your data source in the Settings menu - In your browser, click the 3-dot menu at the top right of the page and click Settings - In the Data Sources section, click to add a new connection - Select the data source type your app uses and provide the name you set when going through the VS Code prompts earlier (e.g., `needful_things` to continue the example from above) - Click to test your connection - Click to confirm the changes 9. Navigate back to the home page in your browser and refresh the page 10. The page should now be working. The migration command covers most situations, but not all - you may need to fix a few remaining issues. If you still see errors, they may be related to query chaining or SQL syntax. See the Special Situations section below for information which may help. If you need assistance tracking down the issues, please [reach out on Slack](https://slack.evidence.dev) in the `#migration` channel ### Completing the Migration Steps Manually The easiest way to migrate your app is to create a app using the latest version of the template, and copy over your markdown pages and queries. These steps will guide you through doing that in the same project so that you can track the changes in version control. 1. In your Evidence project directory, create a new folder called `_legacy_project` 2. Copy all of the files from your existing project into the `_legacy_project` folder - this will serve as a backup, and you will need to reference these in the following steps to copy content back into your project 3. Create another folder called `temporary` 4. Scaffold a new project into this `temporary` folder using the latest version of the template - CLI: `npx degit evidence-dev/template temporary` - This step is required because `degit` only works in an empty folder - After this step, you should have a new evidence project in your `temporary` directory 5. Move all of the files from this `temporary` folder into the root of your project. Then delete the `temporary` folder - Now you should have a `_legacy_project` folder and a new Evidence project in the same workspace 6. Set up your new `sources` directory - In the new `sources` folder, delete any demo data folders so that the folder is empty - you won't need any of those - Create a new folder in your `sources/` directory, with a name for your existing data source (e.g., `sources/my-data-source/`) 7. Copy files from `_legacy_project` into your new project. Make sure to **copy** rather than **move** the files. If the folder already exists in the new project, replace the contents with the contents from `_legacy_project`: - Folders to copy from `_legacy_project` to your new project - `pages/` -> `pages/` - `components/` -> `components/` - `partials/` -> `partials/` - `static/` -> `static/` - `sources` folder - If `_legacy_project` has a `sources` directory, copy the contents of that folder into the `sources/my-data-source` folder in your new project - Files in the root of `_legacy_project` - Any data files in the root of your old project should be copied into your `sources/my-data-source` folder. This includes files with these extensions: - `.duckdb` - `.db` - `.sqlite` - `.sqlite3` - `.csv` - `.parquet` 6. Set up your `queries` directory - If a `queries` directory does not exist in your new project, create that folder now (in the root of your project) - If you don't have any `.sql` files in your `sources/my-data-source` directory, you can move to the next step and leave the `queries` folder empty - For each `.sql` file in your `sources/my-data-source` directory, create a file in `queries` with the same name (e.g., `sources/my-data-source/my-query.sql` --> `queries/my-query.sql`) - Write this query into each `.sql` file you created in `queries`: `select * from [my-data-source].[my-query]` 8. Migrate queries in your markdown files - Changes to make in each markdown file: - If you have frontmatter that references `sources`, change the name from `sources` to `queries` - For each inline query in the file: - Create a `.sql` file in your data source folder using the same name as the query (e.g., `sources/my-data-source/my-query.sql`) and paste in the contents of the query - In your markdown file, replace the contents of the query with `select * from [my-data-source].[my-query]` - If your query is a chained query, check that the reference will still work, and adjust as necessary - If you run into duplicate query names across pages, you will need to create unique names and ensure they are referenced correctly on your markdown page 9. Update templated page syntax - On each templated page, you can replace `$page.params.my_param` with `params.my_param` - The old reference will continue to work but will be phased out in the future in favour of this simpler syntax 10. Run the commands below: ```shell npm install npm run sources npm run dev ``` **Notes:** - `npm run sources` is a new step introduced by USQL. This step runs the queries against your data sources - It is normal to see errors in your terminal at this stage - you need to configure your data source to avoid these (see next step) 11. Configure your data source in the Settings menu - Click the 3-dot menu at the top right of the page and click Settings - In the Data Sources section, click to add a new connection - Select the data source type your app uses and provide a name for your data source. This will appear as a folder within the `sources` directory in your project (e.g., you could use `needful_things` if using the Evidence demo database) - Click to test your connection - Click to confirm the changes 12. Navigate back to the home page in your browser and refresh the page 13. The page should now be working. If you still see errors, they may be related to query chaining or SQL syntax. See the Special Situations section below for information which may help. If you need assistance tracking down the issues, please [reach out on Slack](https://slack.evidence.dev) in the `#migration` channel ## Deployment Changes ### Evidence Cloud 1. Copy environment variables for your app from your local dev environment (Settings page > Deployment) ![env vars](/img/settings-vars.png) 2. Update the environment variables for your Evidence Cloud app by pasting the environment variables from Step 1 ![cloud vars](/img/cloud-settings-edit.png) 3. Click to redeploy your app ### Self-Hosting You will need to update 2 things in your deployment setup to complete the migration to USQL: 1. Update your environment variables - See links in the Resources section for Netlify and Vercel docs - Find the new environment variables in your app's settings menu in your browser (click 3-dot menu at top right > Settings) - then scroll down to Deployment and select your deployment provider - Copy your variables and change them in the configuration for your deployment provider 2. Update the build command - USQL introduces the new `run sources` step to load data into your app from your data sources - Replace the build command in your deployment provider to `npm run sources && npm run build:strict` - See Netlify and Vercel docs in the Resources section ## Special Situations to Migrate ### Script Tags & Javascript References If you use a script tag on a markdown page, you will need to change any variable declarations of of `let` or `var` to `$:`. The reason for this change relates to how the new query engine updates query results - because queries run in the browser and can change based on input, you need to use a reactive variable declaration (that's what `$:` means), which can update itself when the data is instantiated, and when it changes. The good news is that most of what you currently include in a script tag should be able to be migrated to USQL by using parameterized SQL queries. For example: #### Before - Using `let` ```html <script> let filtered_data = my_query.filter(d => d.column === $page.params.my_variable); </script> ``` #### After - Using `$:` ```html <script> $: filtered_data = my_query.filter(d => d.column === $page.params.my_variable); </script> ``` #### Ideal - Refactor to SQL Query in USQL ````html ```filtered_data select * from my_table where column = '${params.my_variable}' ``` ```` ### Query Chaining Our migration steps do not take into account query chaining. In some cases, chained queries will continue to work as normal. In other cases, you will need to make adjustments. Query chaining is not supported in the `sources` directory, but is still supported in `queries` and on your markdown pages. This means that any query chains included in `sources` will need to be replaced with actual references to the tables you need. If you use the VS Code migration command, chained queries found on markdown pages are left on the page rather than being moved to the `sources` directory like other queries. This is because we assume that most chained queries are simple enough for the syntax of your source database to match with the DuckDB syntax they will need to move to. In some cases, the syntax will not line up and you will need to make an adjustment. ### Evidence Plugins If your app includes an Evidence plugin (e.g., [Evidence Labs](https://labs.evidence.dev)): 1. Find the `evidence.plugins.yaml` file in your `_legacy_project` folder and copy the line(s) containing the plugin(s) you're using 2. Paste those lines into the `evidence.plugins.yaml` file in your new project 3. Install the plugin(s) in your project. E.g.,: ```shell npm install --save @evidence-dev/labs ``` ### External Package Dependencies If your project includes external packages installed via npm, you will need to reinstall those packages so that they are reflected in your `package.json` ```bash npm install ``` ## Common Syntax Change Examples - In DuckDB, double quotes are used to reference columns. If you have double quotes in your queries for strings, you will need to change to single quotes - `date_trunc` - in DuckDB, the date part is the first argument to the function and is passed as a string, whereas in some other dialects it is the second argument and is passed as a keyword - `safe_divide` - in DuckDB you can use `number / nullif(other_number, 0) as divided_number` rather than `safe_divide(number, other_number)` - You may need to change how you cast columns to other types. In DuckDB, you can use the `::type` syntax like so: `select order_time::date as order_date` ## Resources - [#migration Slack channel](https://slack.evidence.dev) - [DuckDB SQL Syntax Reference](https://duckdb.org/docs/sql/statements/select) - [Netlify: Modify Environment Variables](https://docs.netlify.com/environment-variables/get-started/#modify-and-delete-environment-variables) - [Netlify: Set your Build Command](https://docs.netlify.com/configure-builds/overview/#set-the-build-command) - [Vercel: Environment Variables](https://vercel.com/docs/projects/environment-variables) - [Vercel: Build Configurations](https://vercel.com/docs/deployments/configure-a-build) --- evidence/sites/docs/pages/guides/best-practices/index.md --- --- title: Best Practices sidebar_position: 3 description: Tips for building performant data apps with Evidence --- Evidence is a very flexible and open-ended tool that allows you to build almost any kind of data app. However, to get the best out of Evidence, here are some principles: 1. [Only source the data you need](#1-only-source-the-data-you-need) 2. [Sort your source queries](#2-sort-your-source-queries) 3. [Change props, not components](#3-change-props-not-components) 4. [Avoid large markdown queries](#4-avoid-large-markdown-queries) ## Source Performance ### 1. Only source the data you need
**Best Practice:** Pre-aggregate data in your source queries, only select the columns and rows you need. Every time you rebuild Evidence, it re-caches all the data from your sources. This can: - Be time-consuming and expensive to cache. - Cause longer load times for your app, as the data comes over the network. It's best to only source the data you need. ### 2. Sort your source queries
**Best Practice:** Sort your source queries. Prioritize columns that appear in `where` clauses in your markdown queries. The cache in Evidence is composed of parquet files. After running `npm run sources`, you can inspect these files in `.evidence/template/static/data`. Sorted queries lead to better compression in parquet files, resulting in faster source build times, lower likelyhood of hitting memory limits, and faster query times in your app. If your source queries are sorted, the client-side query engine is able to take advantage of [Projection Pushdown](https://duckdb.org/2021/06/25/querying-parquet.html#automatic-filter--projection-pushdown) i.e. only loading the rows it needs. ## Interactive Performance ### 3. Change props, not components
**Best Practice:** Use inputs to change props or change queries, not whole components. If you swap out components (for example using `{#if}` blocks), Evidence will re-render the entire component. This can cause a jerky transition as the component is re-rendered. #### Don't do this The entire component is re-rendered when the dropdown changes: ````svelte ```sql categories select * from categories ``` ```sql products select * from products ``` {#if inputs.chart_picker.value == "categories"} {:else} {/if} ```` #### Do this Instead, change which query the component uses with a [ternary operator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Conditional_Operator): ````svelte ```sql categories select * from categories ``` ```sql products select * from products ``` ```` ### 4. Avoid large markdown queries **Best Practice:** Do not return more than ~100,000 rows from queries on your page. Aggregate data in your markdown queries or source queries if needed. Browsers have limited memory, and large datasets can cause slowdowns, increased rendering times and crashes. It's unlikely that you are attempting to visualize 100,000 datapoints on a webpage (an average desktop display only has ~1M pixels) so you can aggregate the data in your markdown queries, or even in you source queries. --- evidence/sites/docs/pages/guides/updating-your-app/index.md --- --- title: Updating Your App sidebar_position: 3 description: Update your app using the CLI or the VS Code extension. --- When new versions of Evidence are released, we post release notes in [Slack](https://slack.evidence.dev). You can also take a look at our pull requests on GitHub to see which changes are being made. We recommend updating regularly to get the latest features and bug fixes. Evidence's is being actively developed, and major releases may introduce breaking changes. We therefore recommend testing updates by running your app in development mode. ## CLI Run `npm install @evidence-dev/evidence@latest @evidence-dev/core-components@latest`. ## VS Code Open the command palette and run `Evidence: Update to Latest Version` ## Getting Help If you run into any problems with updates, reach out on [Slack](https://slack.evidence.dev) or email . --- evidence/sites/docs/pages/components/index.md --- --- title: "Components" sidebar_position: 2 sidebar_link: false --- --- evidence/sites/docs/pages/components/value/index.md --- --- title: Value sidebar_position: 1 --- The Value component accepts a query and displays a formatted value inline in text. By default, `Value` will display the value from the first row of the first column of the referenced data. ```markdown ``` ## Specifying Rows and Columns Optionally supply a `column` and/or a `row` argument to display other values from `data`. **Row Index** `row` is zero-indexed, so `row=0` displays the first row. ```markdown ``` ## Example **Markdown:** ```markdown The most recent month of data began , when there were orders. ``` **Results:** ![summary-sentence](/img/tutorial-img/needful-things-value-in-text-nowindow.png) ## Adding a Placeholder Override errors with the optional `placeholder` argument. This is useful for drafting reports _before_ writing your queries. ```markdown ``` Sales in the last fiscal year were , a change of vs. the prior year. ## Formatting Values Evidence supports a variety of formats - see [value formatting](/core-concepts/formatting) and the `fmt` prop below for more info. ## Aggregated Values Values support basic aggregations such as, `min`, `max`, `median`, `sum`, `avg` ```sql orders SELECT email, item, sales FROM needful_things.orders ```

```markdown ``` ## Customize Color Values

```markdown ``` ## Red Negative Values ```sql NegativeSales SELECT MAX(sales)*-1 as max_sales FROM needful_things.orders ``` If the value is negative, the font color will automatically change to red, overriding any color specified by the color prop.

```markdown ``` ## Options Query name, wrapped in curly braces Column to pull values from Row number to display. 0 is the first row. Text to display in place of an error Format to use for the value ([see available formats](/core-concepts/formatting)) 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. 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.). Adds aggregation to query, column name required. Specifies the font color of the Value. Conditionally sets the font color to red based on whether the selected value is less than 0 --- evidence/sites/docs/pages/components/sankey-diagram/index.md --- --- title: Sankey Diagram sidebar_position: 1 --- The SankeyDiagram component accepts a query and displays a flow from one set of values to another. To display a flow with multiple levels, like these examples, see [Mutli-level](#multi-level) below. ```sql simple_sankey select 'products' as source, 'profits' as target, 100 as amount, 0.67 as percent union all select 'products' as source, 'expenses' as target, 50 as amount, 0.33 as percent union all select 'services' as source, 'profits' as target, 25 as amount, 0.50 as percent union all select 'services' as source, 'expenses' as target, 25 as amount, 0.50 as percent ``` ```sql traffic_data select 'google' as source, 'all_traffic' as target, 100 as count union all select 'direct' as source, 'all_traffic' as target, 50 as count union all select 'facebook' as source, 'all_traffic' as target, 25 as count union all select 'bing' as source, 'all_traffic' as target, 25 as count union all select 'tiktok' as source, 'all_traffic' as target, 25 as count union all select 'twitter' as source, 'all_traffic' as target, 25 as count union all select 'linkedin' as source, 'all_traffic' as target, 25 as count union all select 'pinterest' as source, 'all_traffic' as target, 25 as count union all select 'all_traffic' as source, '/' as target, 50 as count union all select 'all_traffic' as source, '/docs' as target, 150 as count union all select 'all_traffic' as source, '/blog' as target, 25 as count union all select 'all_traffic' as source, '/about' as target, 75 as count ```

```svelte ``` ## Vertical

```svelte ``` # Echarts Options String

```svelte ``` # Node Depth Override ```sql apple_income_statement select 'iphone' as source, 'product revenue' as target, 51 as amount_usd union all select 'mac' as source, 'product revenue' as target, 10 as amount_usd union all select 'ipad' as source, 'product revenue' as target, 8 as amount_usd union all select 'wearables and home' as source, 'product revenue' as target, 9 as amount_usd union all select 'services revenue' as source, 'revenue' as target, 20 as amount_usd union all select 'product revenue' as source, 'revenue' as target, 78 as amount_usd union all select 'revenue' as source, 'gross profit' as target, 43 as amount_usd union all select 'gross profit' as source, 'operating profit' as target, 30 as amount_usd union all select 'gross profit' as source, 'operating expenses' as target, 13 as amount_usd union all select 'revenue' as source, 'cost of revenue' as target, 55 as amount_usd ```

```svelte ``` # Labels ## Node Labels ### `nodeLabels=name` (default)

```svelte ``` ### `nodeLabels=value`

The value labels can be formatted using the `valueFmt` option.

```svelte ``` ### `nodeLabels=full`

```svelte ``` ## Link Labels ### `linkLabels=full` (default) Requires `percentCol` to show percentage beside value

```svelte ``` ### `linkLabels=value`

```svelte ``` ### `linkLabels=percent`

```svelte ``` ## Custom Color Palette

```svelte ``` ## Link Colors ### `linkColor=grey` (default)

```svelte ``` ### `linkColor=source`

```svelte ``` ### `linkColor=target`

```svelte ``` ### `linkColor=gradient`

```svelte ``` ## Multi-level The syntax for multi-level sankey diagrams is the same, but the underlying query must represent all the levels using the same `sourceCol` and `targetCol`, so it is necessary to `union` each level together. `sourceCol` nodes on the next level will be linked to `targetCol` nodes in the previous level with the same name. For example, here is the source for the visuals above. ```svelte ```sql traffic_source select channel as source, 'all_traffic' as target, count(user_id) as count from events.web_events group by 1,2 union all select 'all_traffic' as source, page_route as target, count(user_id) as count from events.web_events group by 1, 2 ‍``` ``` ## Options ### Data Query name, wrapped in curly braces Column to use for the source of the diagram Column to use for the target of the diagram Column to use for the value of the diagram Column to use for the percent labels of the diagram Manual adjustment to location of each node `{{'services revenue': 2}}` 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. 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.). Helper prop for custom chart development - inserts a code block with the current echarts config onto the page so you can see the options used and debug your custom options ### Formatting & Styling Format to use for `valueCol` ([see available formats](/core-concepts/formatting)) Layout direction of the nodes in the diagram. Whether the nodes are sorted by size in the diagram Controls the horizontal alignment of nodes in the diagram. When orient is vertical, nodeAlign controls vertical alignment. The gap between any two rectangles in each column of the the diagram. The node width of rectangle in the diagram. Border color. Only accepts a single color. Border Width. It should be a natural number. Array of custom colours to use for the chart. E.g., `{['#cf0d06','#eb5752','#e88a87']}` Color to use for the links between nodes in the diagram ### Chart Chart title. Appears at top left of chart. Chart subtitle. Appears just under title. Adds labels to the nodes of the diagram Adds labels to the links between nodes Minimum height of the chart area (excl. header and footer) in pixels. Adjusting the height affects all viewport sizes and may impact the mobile UX. ### Custom Echarts Options Custom Echarts options to override the default options. See [reference page](/components/echarts-options/) for available options. Helper prop for custom chart development - inserts a code block with the current echarts config onto the page so you can see the options used and debug your custom options --- evidence/sites/docs/pages/components/details/index.md --- --- title: Details sidebar_position: 1 --- The details component allows you to add a collapsible section to your markdown. This is useful for adding additional information that you don't want to be visible by default. ## Default state

Definition of metrics in Solutions Targets ### Time to Proposal Average number of days it takes to create a proposal for a customer *Calculation:* Sum of the number of days it took to create each proposal, divided by the number of proposals created *Source:* Hubspot

````markdown

```` ## Expanded state

```markdown

``` ## Options The text shown next to the triangle icon. Whether expanded by default. --- evidence/sites/docs/pages/components/bubble-chart/index.md --- --- title: Bubble Chart sidebar_position: 1 queries: - price_vs_volume.sql ---

```markdown ``` ## Examples ### Default

```markdown ``` ### Multi-Series

```markdown ``` ## Options ### Data ### Formatting & Styling ### Axes ### Chart ### Custom Echarts Options ### Interactivity ## Annotations Bubble charts can include [annotations](/components/annotations) using the `ReferenceLine` and `ReferenceArea` components. These components are used within a chart component like so:

```markdown ``` --- evidence/sites/docs/pages/components/echarts-options/index.md --- --- sidebar_position: 98 title: ECharts Options --- `echartsOptions` allow you to customize your chart with any combination of eCharts config options. Many config combinations can result in "broken" looking charts. Proceed with caution, and test your charts, particularly at different screen widths. ECharts settings are specified in config object. Evidence generates this config for you through the props you pass to your chart. If you can't get your chart to look "just right" with standard chart , you can use `echartsOptions` to customize your chart by adding or overriding the eCharts config directly. ## ECharts Options Object The options object is passed as follows. **Note the double curly braces.** ```markdown ``` See the [eCharts docs](https://echarts.apache.org/en/option.html) for a full reference of config options. Note that LLMs such as ChatGPT and GitHub Copilot are reasonably good at generating eCharts options if you explain what you are trying to achieve. ## Series Options Object Often if you are making custom changes to a chart, you will need to adjust options within ECharts' `series`. When you have a multi-series chart, each series shows up separately in the ECharts configuration generated by Evidence. For example, if you have a stacked bar with 4 series, this is what the underlying config object might look like: ```javascript series: [ {type: 'bar', barWidth: 5, name: 'Canada', data: [200,5525,222,444,666]}, {type: 'bar', barWidth: 5, name: 'US', data: [1200,1555,1222,4144,6616]}, {type: 'bar', barWidth: 5, name: 'UK', data: [2060,525,262,4844,4666]}, {type: 'bar', barWidth: 5, name: 'Australia', data: [2200,5555,2252,8444,3666]} ] ``` If you wanted to add a custom border to the bars with `echartsOptions`, you would need to manually repeat for each series. E.g.,

```html ``` With `seriesOptions`, you can specify the changes once and have them applied to all series in the chart, like so: ```country_sales select 'Canada' as country, 2020 as year, 100 as sales union all select 'Canada' as country, 2021 as year, 150 as sales union all select 'Canada' as country, 2022 as year, 200 as sales union all select 'Canada' as country, 2023 as year, 250 as sales union all select 'US' as country, 2020 as year, 200 as sales union all select 'US' as country, 2021 as year, 350 as sales union all select 'US' as country, 2022 as year, 400 as sales union all select 'US' as country, 2023 as year, 450 as sales ```

```svelte ``` ## Print ECharts Config You can print the current eCharts config for a chart by adding `printEchartsConfig=true` to the chart. This will print the full config just below the chart. This includes both any default Evidence config and any `echartsOptions` you have specified, and so can be useful for debugging. ```svelte ``` ## Example Configs ### Customize the Legend Position

```svelte echartsOptions={{ legend: { right: 'right', top: 'middle', align: 'auto', orient: 'vertical', padding: 7, borderColor: '#ccc', borderWidth: 1, }, grid: { right: '120px' } }} ``` ### Add Data Zoom

```svelte echartsOptions={{ dataZoom: [ { start: 0, end: 100, }, ], grid: { bottom: '50px', }, }} ``` ### Add Series Labels Next to Chart

params.seriesName, offset: [0, 0], // [x, y] offset from the end of the line } }, { endLabel: { show: true, formatter: (params) => params.seriesName, offset: [0, 0], // [x, y] offset from the end of the line } } ], grid: { right: '50px', top: '10px' } }} />

```svelte echartsOptions={{ series: [ { endLabel: { show: true, formatter: (params) => params.seriesName, offset: [0, 0], // [x, y] offset from the end of the line } }, { endLabel: { show: true, formatter: (params) => params.seriesName, offset: [0, 0], // [x, y] offset from the end of the line } } ], grid: { right: '50px', top: '10px' } }} ``` ### Add Axis Pointer to Tooltip

```svelte echartsOptions={{ tooltip: { trigger: 'axis', axisPointer: { type: 'cross', label: { backgroundColor: '#6a7985' } } }, }} ``` --- evidence/sites/docs/pages/components/link-button/index.md --- --- title: Link Button sidebar_position: 1 ---

My Link Button

```markdown My Link Button ``` ## Options Renders a button that, when clicked, navigates to the specified URL. It can accept either a full external link (e.g. `https://google.com`) or link to another page within your evidence app (e.g. `/sales/performance`). --- evidence/sites/docs/pages/components/download-data/index.md --- --- title: Download Data sidebar_position: 1 --- ```categories select category, sum(sales) as sales from needful_things.orders group by all order by sales desc ``` The Download Data component allows you to place a link on your page to download a specified dataset to CSV.

```svelte ``` ## Examples ### Custom Text

```svelte ``` ### Custom Query ID

```svelte ``` ## Options Query name, wrapped in curly braces Whether link is visible. If using as part of a custom component, you can pass a variable representing the hover state of your component to control visibility. Label to show on the link Label to include as the start of the CSV filename. If no queryID is supplied, "evidence_download" is used. --- evidence/sites/docs/pages/components/slider/index.md --- --- title: Slider sidebar_position: 1 --- Creates a Slider input with default min, max and step values

````markdown ```` Min and Max values can be defined, the step property and define the incremental value of the slider

````markdown ```` showMaxMin property can hide the Max and Min values with false, by default showMaxMin is true

````markdown ```` The default size of the slider can be altered with the size property using; medium, large or full

````markdown ````

````markdown ```` ````sql flight_data SELECT CAST(fare AS INT) AS fare, CAST((SELECT MAX(fare) FROM flights) AS INT) AS max_fare, FROM flights LIMIT 100 ```` ## Specifying Dynamic Columns Supply data with specified column names for minColumn, maxColumn, and/or defaultValue. The first row’s value in each of these columns will determine the minimum, maximum, or default value, respectively. ````markdown ```` # Slider ## Options name of the slider, used to reference the selected value elsewhere as `{inputs.name}` Sets the initial value of the silder Sets the minimum value on the slider. Negative Values accepted. Sets the maximum value on the slider. This value must be larger than the min. Defines the incremental value of the slider Hides or shows min and max value markers on slider. Sets the length of the slider. Options are "medium", large" or "full". A empty string of any other strings will not result in default size. --- evidence/sites/docs/pages/components/scatter-plot/index.md --- --- title: Scatter Plot sidebar_position: 1 queries: - price_vs_volume.sql ---

```markdown ``` ## Examples ### Default

```markdown ``` ### Multi-Series

```markdown ``` ## Options ### Data Query name, wrapped in curly braces Column to use for the x-axis of the chart Column(s) to use for the y-axis of the chart Column to use as the series (groups) in a multi-series chart Whether to apply default sort to your data. Default is x ascending for number and date x-axes, and y descending for category x-axes Column to use as the title for each tooltip. Typically, this is a name to identify each point. 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. 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.). ### Formatting & Styling Format to use for x column ([see available formats](/core-concepts/formatting)) Format to use for y column ([see available formats](/core-concepts/formatting)) Options for which shape to use for scatter points Change size of all points on the chart % of the full color that should be rendered, with remainder being transparent Color to override default series color. Only accepts a single color. Width of line surrounding each shape Color to use for outline if outlineWidth > 0 Array of custom colours to use for the chart. E.g., `{['#cf0d06','#eb5752','#e88a87']}` Apply a specific color to each series in your chart. Unspecified series will receive colors from the built-in palette as normal. Note the double curly braces required in the syntax `seriesColors={{"Canada": "red", "US": "blue"}}` Apply a specific order to the series in a multi-series chart. ### Axes Whether to use a log scale for the y-axis Base to use when log scale is enabled Name to show under x-axis. If 'true', formatted column name is used. Only works with swapXY=false Name to show beside y-axis. If 'true', formatted column name is used. Turns on/off gridlines extending from x-axis tick marks (vertical lines when swapXY=false) Turns on/off gridlines extending from y-axis tick marks (horizontal lines when swapXY=false) Turns on/off value labels on the x-axis Turns on/off value labels on the y-axis Turns on/off thick axis line (line appears at y=0) Turns on/off thick axis line (line appears directly alongside the y-axis labels) Turns on/off tick marks for each of the x-axis labels Turns on/off tick marks for each of the y-axis labels Starting value for the x-axis Maximum value for the x-axis Starting value for the y-axis Maximum value for the y-axis ### Chart Chart title. Appears at top left of chart. Chart subtitle. Appears just under title. Turns legend on or off. Legend appears at top center of chart. Minimum height of the chart area (excl. header and footer) in pixels. Adjusting the height affects all viewport sizes and may impact the mobile UX. Which chart renderer type (canvas or SVG) to use. See ECharts' [documentation on renderers](https://echarts.apache.org/handbook/en/best-practices/canvas-vs-svg/). ### Custom Echarts Options Custom Echarts options to override the default options. See [reference page](/components/echarts-options/) for available options. Custom Echarts options to override the default options for all series in the chart. This loops through the series to apply the settings rather than having to specify every series manually using `echartsOptions` See [reference page](/components/echarts-options/) for available options. Helper prop for custom chart development - inserts a code block with the current echarts config onto the page so you can see the options used and debug your custom options ### Interactivity Group name to connect this chart to other charts for synchronized tooltip hovering. Charts with the same `connectGroup` name will become connected ## Annotations Scatter plots can include [annotations](/components/annotations) using the `ReferenceLine` and `ReferenceArea` components. These components are used within a chart component like so: ```html ``` --- evidence/sites/docs/pages/components/bar-chart/index.md --- --- title: Bar Chart sidebar_position: 1 queries: - orders_by_month.sql - orders_by_category_2021.sql - orders_by_item_all_time.sql - categories_by_channel.sql ---

```markdown ``` ## Examples ### Default

```markdown ``` ### Stacked

```markdown ``` ### 100% Stacked

```markdown ``` ### Grouped

```markdown ``` ### Horizontal

```markdown ``` ### Horizontal Stacked

```markdown ``` ### Horizontal 100% Stacked

```markdown ``` ### Horizontal Grouped

```markdown ``` ### Value Labels

```markdown ``` ### Custom Color Palette

```markdown ``` ### Secondary / Dual y Axis

```markdown ``` ### Secondary / Dual Axis with Line

```markdown ``` ## Options ### Data ### Formatting & Styling ### Value Labels ### Axes ### Chart ### Custom Echarts Options ### Interactivity ## Annotations ```sql target_data select 8333 as target, '100k ARR' as name ``` Bar charts can include [annotations](/components/annotations) using the `ReferenceLine` and `ReferenceArea` components. These components are used within a chart component like so: ```html ``` --- evidence/sites/docs/pages/components/big-link/index.md --- --- title: Big Link sidebar_position: 1 ---

My Big Link

```markdown My Big Link ``` ## Options Renders a link that, when clicked, navigates to the specified URL. It can accept either a full external link (e.g. `https://google.com`) or link to another page within your evidence app (e.g. `/sales/performance`). --- evidence/sites/docs/pages/components/dropdown/index.md --- --- title: Dropdown sidebar_position: 1 --- Creates a dropdown menu with a list of options that can be selected. The selected option can be used to filter queries or in markdown. To see how to filter a query using a dropdown, see [Filters](/core-concepts/filters). ```sql categories select distinct category as category_name, upper(left(category, 3)) as abbrev from needful_things.orders ```

Selected: {inputs.category1.value}

````markdown Selected: {inputs.category1.value} ```` ## Examples ### Dropdown using Options from a Query

Selected: {inputs.category2.value}

````markdown ```` Selected: {inputs.category2.value} ### With a Title

Selected: {inputs.category3.value}

````markdown Selected: {inputs.category3.value} ```` ### With a Default Value

Selected: {inputs.category4.value}

````markdown Selected: {inputs.category4.value} ```` ### With Hardcoded Options

Selected: {inputs.hardcoded.value}

````markdown Selected: {inputs.hardcoded.value} ```` ### Alternative Labels This example uses a column called `abbrev`, which contains an alternate label for each category

Selected: {inputs.category_abbrev.value}

````markdown ```` Selected: {inputs.category_abbrev.value} ### Multi-Select When using multi-select dropdowns, you need to use an alternative SQL expression: `where column_name IN ${inputs.my_input.value}` Note: - The use of the IN operator - No single quotes used around the `${}`

Selected: {inputs.category_multi.value}

````markdown Selected: {inputs.category_multi.value} ```` ### Filtering a Query ```sql order_history select id, order_datetime, category, item, sales from needful_things.orders limit 100 ``` Starting with this table of orders:

````markdown ```sql order_history select id, order_datetime, category, item, sales from needful_things.orders limit 100 ``` ```` Use this input to filter the results: ```sql orders_filtered select * from ${order_history} where category in ${inputs.category.value} ```

Filtered Row Count: {orders_filtered.length}

````markdown ```sql filtered_query select * from source_name.table where column_name like '${inputs.name_of_dropdown.value}' ``` Filtered Row Count: {orders_filtered.length} ```` ### Multiple defaultValues

Selected: {inputs.category_multi_default.value}

````svelte Selected: {inputs.category_multi_default.value} ```` ### Select all by Default Value with Multiple Select and return all values in the dropdown list, requires "multiple" prop.

Selected: {inputs.category_multi_selectAllByDefault.value}

````markdown Selected: {inputs.category_multi_selectAllByDefault.value} ```` # Dropdown ## Options # DropdownOption ## Options The DropdownOption component can be used to manually add options to a dropdown. This is useful to add a default option, or to add options that are not in a query. --- evidence/sites/docs/pages/components/modal/index.md --- --- title: Modal sidebar_position: 1 ---

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

```markdown Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. ``` ## Styling Modals support markdown in the body, but you need to leave whitespace between the text and the modal tags.

**bold** and _italic_ text is supported.

```markdown **bold** and _italic_ text is supported. ``` ## Including Components ```sql orders_by_month select order_month, sum(sales) as sales_usd0k from needful_things.orders group by all ``` You can include components inside a Modal, like charts or tables:

```svelte ``` ## Options --- evidence/sites/docs/pages/components/heatmap/index.md --- --- title: Heatmap sidebar_position: 1 --- ```orders select category, dayname(order_datetime) as day, dayofweek(order_datetime) as day_num, count(*) as order_count from needful_things.orders group by all order by category, day_num ```

```markdown ``` ## Data Structure Heatmap requires your data to contain 2 categorical columns (1 for the x-axis and 1 for the y-axis) and 1 numeric column. #### Example ```sql example SELECT 'West' as region, 'A' as product, 120 as sales UNION ALL SELECT 'West', 'B', 200 UNION ALL SELECT 'West', 'C', 150 UNION ALL SELECT 'East', 'A', 110 UNION ALL SELECT 'East', 'B', 315 UNION ALL SELECT 'East', 'C', 450 ``` ### Unpivoting your Data If you have data spread across columns, you can use the `UNPIVOT` feature in your SQL query to prepare the data for the heatmap. #### Example If you have a query result called `region_sales`: ```sql region_sales SELECT 'West' as region, 120 as "A", 200 as "B", 150 as "C" UNION ALL SELECT 'East', 110, 315, 450 ``` You can use `UNPIVOT` like so: ```sql UNPIVOT ${region_sales} on COLUMNS(* EXCLUDE(region)) INTO NAME product VALUE sales ``` Which will return this table, which can be passed into the Heatmap: ```sql region_sales_unpivoted SELECT 'West' as region, 'A' as product, 120 as sales UNION ALL SELECT 'West', 'B', 200 UNION ALL SELECT 'West', 'C', 150 UNION ALL SELECT 'East', 'A', 110 UNION ALL SELECT 'East', 'B', 315 UNION ALL SELECT 'East', 'C', 450 order by region desc, product ``` **Note on Date Columns** Heatmap currently only works with string columns. If you would like to use a date column, cast it to a string in your SQL query before passing it into the Heatmap ## Examples ### Basic Heatmap

```markdown ``` ### Custom Color Scale

```svelte ``` ### Rotated Labels ```item_state select item, state, count(1) as orders from needful_things.orders group by all order by state asc, item asc ```

```svelte ``` ## Options ### Data ### Formatting & Styling ### Axes ### Chart ### Custom Echarts Options ### Interactivity --- evidence/sites/docs/pages/components/tabs/index.md --- --- title: Tabs sidebar_position: 1 ---

Content of the First Tab You can use **markdown** here too! Content of the Second Tab Here's a [link](https://www.google.com)

```markdown Content of the First Tab You can use **markdown** here too! Content of the Second Tab Here's a [link](https://www.google.com) ``` ## Examples ### Custom Color

Content of the First Tab Content of the Second Tab

```markdown Content of the First Tab Content of the Second Tab ``` ### Persist Selected Tab to URL

Click Second id Tab and notice the the url updates! Refresh the page and the tab you selected persists!

```markdown Click Second id Tab and notice the the url updates! Refresh the page and the tab you selected persists! ``` # Tabs ## Options Unique Id for this set of tabs. When set, the selected tab is included in the URL so it can be shared. Color for the active tab. # Tab ## Options Label for the tab Unique Id for this tab. Only needed if 2 tabs have the same label (not recommended). --- evidence/sites/docs/pages/components/sparkline/index.md --- --- title: Sparkline sidebar_position: 1 --- ```sql orders_by_month select order_month as month, sum(sales) as sales_usd0k, count(1) as orders from needful_things.orders group by all ``` ```sql orders_by_category select category, order_month as month, sum(sales) as sales_usd0k, count(1) as orders from needful_things.orders group by all ```

```markdown ``` ## Examples ### Connected Sparkline

```html ``` ## Options ### Data Query name, wrapped in curly braces Categorical column to use for the x-axis Numeric column to use for the y-axis Chart type for sparkline 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. 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.). ### Formatting & Styling Color to use for the visualization. For area sparklines, choose the color for the line and the area color will be automatically appplied in a lighter shade. Format to use for value column ([see available formats](/core-concepts/formatting)) Format to use for date column ([see available formats](/core-concepts/formatting)) ### Axes Whether to truncate the y-axis to enhance visibility ### Sizing Height of sparkline in pixels Width of sparkline in pixels ### Interactivity Turn on or off tooltip behaviour on hover. If off, chart will be a staticly rendered SVG (better for page performance). If on, you will be able to see dates/values when hovering over the sparkline Group name to connect this sparkline to other charts for synchronized tooltip hovering. Charts with the same `connectGroup` name will become connected --- evidence/sites/docs/pages/components/all-components/index.md --- --- sidebar_position: 0 title: All Components hide_title: false hide_table_of_contents: false description: A list of all the components available in the Evidence library. --- ## Data Components

### [Value](/components/value) Value

### [Big Value](/components/big-value)

### [Data Table](/components/data-table)

### [Dimension Grid](/components/dimension-grid)

## Charts ### [Line](/components/line-chart)

Line Chart - Single Series

Line Chart - Multiple Series

Line Chart - Multiple Y Columns

### [Area](/components/area-chart)

Area Chart

Stacked Area Chart

100% Stacked Area Chart

### [Bar](/components/bar-chart)

Bar Chart

Stacked Bar Chart

100% Stacked Bar Chart

Grouped Bar Chart

Horizontal Bar Chart

Horizontal Stacked Bar Chart

Horizontal 100% Stacked Bar Chart

Horizontal Grouped Bar Chart

Long Bar Chart

### [Scatter](/components/scatter-plot)

Scatter Plot

Scatter Plot - Multiple Series

### [Bubble](/components/bubble-chart)

Bubble Chart

Bubble Chart - Multiple Series

### [Funnel](/components/funnel-chart)

Funnel Default

Funnel Side Aligned

### [Sankey](/components/sankey-diagram)

Default Sankey

Vertical Sankey

### [Heatmap](/components/heatmap)

Basic Heatmap

Customized Heatmap

### [Calendar Heatmap](/components/heatmap)

Default Calendar Heatmap

Multi-year Calendar Heatmap

### [Histogram](/components/histogram)

Default Histogram

### [Box Plot](/components/box-plot)

Default Box Plot

Horizontal Box Plot

### [Mixed Type Charts](/components/mixed-type-charts)

Bar and Line

### [Annotations](/components/annotations)

Reference Line - y-axis

Reference Line - x-axis

Reference Area - x-axis

Reference Area - y-axis

Reference Area - Box

### Maps

Area Map

Point Map

Bubble Map

Base Map

US Map

### [Custom ECharts](/components/custom-echarts)

Custom ECharts Treemap

Custom ECharts Funnel

Custom ECharts Pie Chart

Custom ECharts Donut Chart

Advanced ECharts Example

## UI Components

### [Accordion](/components/accordion)

### [Alert](/components/alert)

### [Details](/components/details)

### [Grid](/components/grid)

### [Modal](/components/modal)

### [Tabs](/components/tabs)

## Input Components

### [Button Group](/components/button-group)

### [Dropdown](/components/dropdown)

### [TextInput](/components/text-input)

### [DateRange](/components/date-range)

--- evidence/sites/docs/pages/components/big-value/index.md --- --- title: Big Value sidebar_position: 1 queries: - orders_with_comparisons.sql --- Big Value displays a large value, and can be configured to include a comparison and a sparkline.

```markdown ``` ## Examples ### Default

```markdown ``` ### Comparisons

```markdown ``` ### Multiple cards Multiple cards will align themselves into a row.

```markdown ``` ### Linking to other pages The link property makes the Value component clickable, allowing navigation to other pages.

```html ``` ### Non-Delta Comparisons

```html ``` ### Sparkline

```html ``` ## Options ### Data Used to navigate to other pages. Can be a full external link like `https://google.com` or an internal link like `/sales/performance` ### Comparison Options ### Sparkline --- evidence/sites/docs/pages/components/funnel-chart/index.md --- --- title: Funnel Chart sidebar_position: 1 --- ```sql funnel_data select * from ( select 150 as customers, 'Show' as stage, 1 as stage_id union all select 102 as customers, 'Click' as stage, 2 as stage_id union all select 49 as customers, 'Visit' as stage, 3 as stage_id union all select 40 as customers, 'Inquiry' as stage, 4 as stage_id union all select 14 as customers, 'Order' as stage, 5 as stage_id ) order by stage_id asc ```

```markdown ``` ## Examples ### Ascending

```markdown ``` ### Alignment

```markdown ``` ### Show Percent Label

```markdown ``` ## Options ### Data ### Formatting & Styling ### Chart ### Custom Echarts Options ### Interactivity --- evidence/sites/docs/pages/components/text-input/index.md --- --- title: Text Input sidebar_position: 1 --- Creates a text input that can be used to filter or search To see how to filter a query using a text input, see [Filters](/core-concepts/filters).

Selected: {inputs.text_input_name}

````markdown Selected: {inputs.text_input_name} ```` ## Examples ### Basic Text Input

Selected: {inputs.name_of_input}

````markdown Selected: {inputs.name_of_input} ```` ### With Title

Selected: {inputs.text_input2}

````markdown Selected: {inputs.text_input2} ```` ### With Placeholder

Selected: {inputs.text_input3}

````markdown Selected: {inputs.text_input3} ```` ### With Default Text Prefilled

Selected: {inputs.text_input4}

````markdown Selected: {inputs.text_input4} ```` ### Fuzzy Finding (Searching) `TextInput` provides an easy-to-use shortcut for [fuzzy finding](https://duckdb.org/docs/sql/functions/char#text-similarity-functions). Note that this is different than `LIKE`, as it does not require a direct substring, and is useful in situtations where spelling may be unknown, like names. You can reference it by using the syntax `{inputs.your_input_name.search('column_name')}`, and it returns a number between 0 and 1. ## Usage Assuming you had some TextInput `first_name_search`: ```sql SELECT * FROM users ORDER BY {inputs.first_name_search.search('first_name')} LIMIT 10 -- Optionally limit to only show the 10 closest results ``` becomes ```sql SELECT * FROM users ORDER BY damerau_levenshtein(first_name, '{inputs.first_name_search}') LIMIT 10 -- Optionally limit to only show the 10 closest results ``` ## Options Name of the text input, used to reference the selected value elsewhere as `{inputs.name.value}` Title displayed above the text input Alternative placeholder text displayed in the text input Hide the component when the report is printed --- evidence/sites/docs/pages/components/last-refreshed/index.md --- --- title: Last Refreshed sidebar_position: 1 --- Displays the last time the data was refreshed. This component is useful for showing users how up-to-date the data is.

```markdown ``` ## Examples ### Alternative Prefix

```markdown ``` ## Options --- evidence/sites/docs/pages/components/box-plot/index.md --- --- title: Box Plot sidebar_position: 1 queries: - sales_distribution_by_channel.sql ---

```markdown ``` ## Data Structure The BoxPlot component requires pre-aggregated data, with one row per box you would like to display. There are 2 ways to pass in the values needed to construct the box: **1. Explicitly define each value (e.g., `min`, `intervalBottom`, `midpoint`, `intervalTop`, `max`)** ```sql boxplot select channel as name, first_quartile as intervalBottom, median as midpoint, third_quartile as intervalTop from ${sales_distribution_by_channel} ``` This example table excludes whiskers which would be defined with `min` and `max` columns **2. Define a `midpoint` and a `confidenceInterval` - this will add the interval to the midpoint to get the max, and subtract to get the min** ```sql boxplot_with_confidence_interval select channel as name, median as midpoint, 20 as confidence_interval from ${sales_distribution_by_channel} ``` ## Examples ### Basic Box Plot

```markdown ``` ### Horizontal Box Plot

```markdown ``` ### Box Plot with Whiskers

```markdown ``` ### Box Plot with Custom Colors

```markdown ``` ## Options ### Data ### Formatting & Styling ### Axes ### Chart ### Custom Echarts Options ### Interactivity ## Annotations Box plots can include [annotations](/components/annotations) using the `ReferenceLine` and `ReferenceArea` components. These components are used within a chart component like so: ```html ``` --- evidence/sites/docs/pages/components/index/index.md --- --- title: "Components" sidebar_position: 2 sidebar_link: false --- --- evidence/sites/docs/pages/components/data-table/index.md --- --- title: Data Table sidebar_position: 1 --- ## Examples ### Displaying All Columns in Query ```orders_summary select * from needful_things.orders order by id limit 100 ```

```svelte ``` ### Selecting Specific Columns

```svelte ``` ### Custom Column Formatting You can use the `fmt` prop to format your columns using [built-in format names or Excel format codes](/core-concepts/formatting/)

```svelte ``` #### Formatting Driven by Another Column ```country_summary_fmts select *, case when country in ('Austria', 'Ukraine') then 'eur' when country = 'Sweden' then 'sek' when country = 'Vietnam' then '"₫"#,##0' else 'usd' end as custom_format from ${country_summary} ``` This example includes a `custom_format` column, which contains a different currency format code for many of the rows.

```svelte ``` ### Search

```svelte ``` ### Sort ```svelte ``` ### Deltas ```sql country_summary select date '2020-04-30' as date, 87 as value_usd, 0.0234 as yoy, 'Austria' as country, 'B' as category, 100384 as country_id, 'AT' as country_code, 'https://flaglog.com/codes/standardized-rectangle-120px/AT.png' as flag, 'https://www.google.ca/search?q=austria' as country_url union all select date '2020-05-01' as date, 95 as value_usd, 0.0534 as yoy, 'Australia' as country, 'C' as category, 104942 as country_id, 'AU' as country_code, 'https://flaglog.com/codes/standardized-rectangle-120px/AU.png' as flag, 'https://www.google.ca/search?q=australia' as country_url union all select date '2020-05-02' as date, 163 as value_usd, 0.0264 as yoy, 'Brazil' as country, 'A' as category, 100842 as country_id, 'BR' as country_code, 'https://flaglog.com/codes/standardized-rectangle-120px/BR.png' as flag, 'https://www.google.ca/search?q=brazil' as country_url union all select date '2020-05-03' as date, 174 as value_usd, 0.0727 as yoy, 'Canada' as country, 'A' as category, 104975 as country_id, 'CA' as country_code, 'https://flaglog.com/codes/standardized-rectangle-120px/CA.png' as flag, 'https://www.google.ca/search?q=canada' as country_url union all select date '2020-05-04' as date, 214 as value_usd, -0.1223 as yoy, 'Chile' as country, 'B' as category, 100644 as country_id, 'CL' as country_code, 'https://flaglog.com/codes/standardized-rectangle-120px/CL.png' as flag, 'https://www.google.ca/search?q=chile' as country_url union all select date '2020-05-05' as date, 342 as value_usd, 0.0124 as yoy, 'Denmark' as country, 'B' as category, 102948 as country_id, 'DK' as country_code, 'https://flaglog.com/codes/standardized-rectangle-120px/DK.png' as flag, 'https://www.google.ca/search?q=denmark' as country_url union all select date '2020-05-06' as date, 331 as value_usd, 0.0252 as yoy, 'Estonia' as country, 'D' as category, 102495 as country_id, 'EE' as country_code, 'https://flaglog.com/codes/standardized-rectangle-120px/EE.png' as flag, 'https://www.google.ca/search?q=estonia' as country_url union all select date '2020-05-07' as date, 98 as value_usd, 0.0754 as yoy, 'Finland' as country, 'B' as category, 104962 as country_id, 'FI' as country_code, 'https://flaglog.com/codes/standardized-rectangle-120px/FI.png' as flag, 'https://www.google.ca/search?q=finland' as country_url union all select date '2020-05-08' as date, 128 as value_usd, -0.0246 as yoy, 'Ghana' as country, 'C' as category, 100599 as country_id, 'GH' as country_code, 'https://flaglog.com/codes/standardized-rectangle-120px/GH.png' as flag, 'https://www.google.ca/search?q=ghana' as country_url union all select date '2020-05-09' as date, 153 as value_usd, 0.0447 as yoy, 'Honduras' as country, 'D' as category, 102494 as country_id, 'HN' as country_code, 'https://flaglog.com/codes/standardized-rectangle-120px/HN.png' as flag, 'https://www.google.ca/search?q=honduras' as country_url union all select date '2020-05-10' as date, 384 as value_usd, -0.0255 as yoy, 'India' as country, 'A' as category, 101948 as country_id, 'IN' as country_code, 'https://flaglog.com/codes/standardized-rectangle-120px/IN.png' as flag, 'https://www.google.ca/search?q=india' as country_url union all select date '2020-05-11' as date, 234 as value_usd, 0.0855 as yoy, 'Ireland' as country, 'B' as category, 100987 as country_id, 'IE' as country_code, 'https://flaglog.com/codes/standardized-rectangle-120px/IE.png' as flag, 'https://www.google.ca/search?q=ireland' as country_url union all select date '2020-05-12' as date, 67 as value_usd, 0.0635 as yoy, 'Jamaica' as country, 'C' as category, 101248 as country_id, 'JM' as country_code, 'https://flaglog.com/codes/standardized-rectangle-120px/JM.png' as flag, 'https://www.google.ca/search?q=jamaica' as country_url union all select date '2020-05-13' as date, 125 as value_usd, -0.0232 as yoy, 'Kenya' as country, 'C' as category, 101947 as country_id, 'KE' as country_code, 'https://flaglog.com/codes/standardized-rectangle-120px/KE.png' as flag, 'https://www.google.ca/search?q=kenya' as country_url union all select date '2020-05-14' as date, 118 as value_usd, -0.0343 as yoy, 'Lebanon' as country, 'D' as category, 108849 as country_id, 'LB' as country_code, 'https://flaglog.com/codes/standardized-rectangle-120px/LB.png' as flag, 'https://www.google.ca/search?q=lebanon' as country_url union all select date '2020-05-15' as date, 263 as value_usd, 0.0883 as yoy, 'Mexico' as country, 'B' as category, 100763 as country_id, 'MX' as country_code, 'https://flaglog.com/codes/standardized-rectangle-120px/MX.png' as flag, 'https://www.google.ca/search?q=mexico' as country_url union all select date '2020-05-16' as date, 211 as value_usd, 0.0395 as yoy, 'Nigeria' as country, 'A' as category, 100837 as country_id, 'NG' as country_code, 'https://flaglog.com/codes/standardized-rectangle-120px/NG.png' as flag, 'https://www.google.ca/search?q=nigeria' as country_url union all select date '2020-05-17' as date, 192 as value_usd, 0.0234 as yoy, 'Oman' as country, 'D' as category, 100993 as country_id, 'OM' as country_code, 'https://flaglog.com/codes/standardized-rectangle-120px/OM.png' as flag, 'https://www.google.ca/search?q=oman' as country_url union all select date '2020-05-18' as date, 59 as value_usd, 0.0828 as yoy, 'Philippines' as country, 'D' as category, 104128 as country_id, 'PH' as country_code, 'https://flaglog.com/codes/standardized-rectangle-120px/PH.png' as flag, 'https://www.google.ca/search?q=philippines' as country_url union all select date '2020-05-19' as date, 113 as value_usd, 0.0554 as yoy, 'Qatar' as country, 'C' as category, 100181 as country_id, 'QA' as country_code, 'https://flaglog.com/codes/standardized-rectangle-120px/QA.png' as flag, 'https://www.google.ca/search?q=qatar' as country_url union all select date '2020-05-20' as date, 190 as value_usd, 0.0134 as yoy, 'Romania' as country, 'A' as category, 101384 as country_id, 'RO' as country_code, 'https://flaglog.com/codes/standardized-rectangle-120px/RO.png' as flag, 'https://www.google.ca/search?q=romania ! startups' as country_url union all select date '2020-05-21' as date, 190 as value_usd, -0.0554 as yoy, 'Sweden' as country, 'B' as category, 101847 as country_id, 'SE' as country_code, 'https://flaglog.com/codes/standardized-rectangle-120px/SE.png' as flag, 'https://www.google.ca/search?q=sweden' as country_url union all select date '2020-05-22' as date, 248 as value_usd, 0.0254 as yoy, 'Thailand' as country, 'C' as category, 104837 as country_id, 'TH' as country_code, 'https://flaglog.com/codes/standardized-rectangle-120px/TH.png' as flag, 'https://www.google.ca/search?q=thailand' as country_url union all select date '2020-05-23' as date, 168 as value_usd, 0.0294 as yoy, 'Ukraine' as country, 'C' as category, 101938 as country_id, 'UA' as country_code, 'https://flaglog.com/codes/standardized-rectangle-120px/UA.png' as flag, 'https://www.google.ca/search?q=ukraine' as country_url union all select date '2020-05-24' as date, 101 as value_usd, 0.0234 as yoy, 'Vietnam' as country, 'A' as category, 104948 as country_id, 'VN' as country_code, 'https://flaglog.com/codes/standardized-rectangle-120px/VN.png' as flag, 'https://www.google.ca/search?q=vietnam' as country_url union all select date '2020-05-25' as date, 67 as value_usd, 0.0294 as yoy, 'Yemen' as country, 'B' as category, 100774 as country_id, 'YE' as country_code, 'https://flaglog.com/codes/standardized-rectangle-120px/YE.png' as flag, 'https://www.google.ca/search?q=yemen' as country_url union all select date '2020-05-26' as date, 100 as value_usd, 0.011 as yoy, 'Zimbabwe' as country, 'A' as category, 100337 as country_id, 'ZW' as country_code, 'https://flaglog.com/codes/standardized-rectangle-120px/ZW.png' as flag, 'https://www.google.ca/search?q=zimbabwe' as country_url ```

```svelte ``` ### Sparklines Sparklines require an array inside a cell of your table. You can create an array using the `array_agg()` function in DuckDB syntax. Below is an example query using this function, and the resulting DataTable. ```sql categories WITH monthly_sales AS ( SELECT category, DATE_TRUNC('month', order_datetime) AS date, SUM(sales) AS monthly_sales FROM needful_things.orders GROUP BY category, DATE_TRUNC('month', order_datetime) ) SELECT category, sum(monthly_sales) as total_sales, ARRAY_AGG({'date': date, 'sales': monthly_sales}) AS sales FROM monthly_sales GROUP BY category order by total_sales desc ```

```svelte ``` ### Bar Chart Column

```svelte ``` ### Total Row Default total aggregation is `sum`

```svelte ``` #### Using Built-in Aggregation Functions ```country_example select * from ${countries} limit 5 ```

```svelte ``` #### Custom Aggregations Values

```svelte ``` #### Custom Total Formats

```svelte ``` ### Conditional Formatting #### Default (`colorScale=positive`)

```svelte ``` #### `colorScale=negative`

```svelte ``` #### `colorScale=info`

```svelte ``` #### Custom Colors When you pass a custom color to `colorScale`, Evidence will create a color palette for you, starting at white (or black, depending on the selected theme) and ending at the color you provided. See examples further down the page to see how to specify a custom color palette with multiple colors. ```orders_by_category select order_month as month, category, sum(sales) as sales_usd0k, count(1) as num_orders_num0, sum(sales) / count(1) as aov_usd2 from needful_things.orders group by all ```

```svelte ``` ### Custom Color Palettes ```numbers select 'A' as name, 1 as number union all select 'B',2 union all select 'C',3 union all select 'D',4 union all select 'E',5 union all select 'F',6 union all select 'G',7 union all select 'H',8 union all select 'I',9 union all select 'J',10 order by number asc ``` #### Diverging Scale

```svelte ``` #### Heatmap

```svelte ``` #### Color Breakpoints Use `colorBreakpoints` or `colorMid`/`colorMin`/`colorMax` to control which values are assigned to which sections of the color scale

```svelte ``` #### Create Scale from Another Column The `number` column in this example has a color scale defined by the `scale_defining_number` column, rather than by its own values. ```numbers_othercol select 'A' as name, 1 as number, 2 as scale_defining_number, 'usd' as fmt union all select 'B',2,10,'eur' union all select 'C',3,30,'num0' union all select 'D',4,20,'pct' union all select 'E',5,10,'usd' union all select 'F',6,5,'pct' union all select 'G',7,1,'pct' union all select 'H',8,44,'eur' union all select 'I',9,4,'#,##0.00"kg"' union all select 'J',10,55, 'usd' order by number asc ```

```svelte ``` ### Red Negatives ```negatives select 'A' as name, -5 as number,0 as status union all select 'B', -4 as number, 1 as status union all select 'C', -3 as number, 2 as status union all select 'D', -2 as number,0 union all select 'E', -1 as number,1 union all select 'F', 0 as number,1 union all select 'G', 1 as number,2 union all select 'H', 2 as number,2 union all select 'I', 3 as number,0 union all select 'J', 4 as number,0 order by number asc ```

```svelte ``` ### 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](/reference/markdown/#storing-images-and-static-files). In this example, `flag` is either an absolute path or a relative path to the image.

```svelte ``` ### Link Columns #### Link Column with Unique Labels

```svelte ``` #### Link Column with Consistent String Label

```svelte ``` ### HTML Content ```sql html_in_table select 'Bold text' as "HTML in Table", 0 as row_number union all select 'Italic text', 1 union all select 'Link', 2 union all select '

', 3 union all select 'Inline Code
is supported', 4 order by row_number ```

````markdown ```sql html_in_table select 'Bold text' as "HTML in Table", 0 as row_number union all select 'Italic text', 1 union all select 'Link', 2 union all select '

', 3 union all select 'Inline Code
is supported', 4 order by row_number ``` ```` To apply styling to most HTML tags, you should add the `class=markdown` attribute to the tag in your column. This will apply the same styling as the markdown renderer. ### Row Links #### External Links 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`)

Click on a row to navigate using the row link:

```svelte ``` #### Link to Pages in Your App In this example, the SQL query contains a column with links to parameterized pages in the app. Below is an example of the SQL that could be used to generate such links: ```sql 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): ```svelte ``` 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

```svelte ``` #### Row Shading + No Row Lines

```svelte ``` #### No Lines or Shading

```svelte ``` ### Column Alignment

```svelte ``` ### Custom Column Titles

```svelte ``` ### Raw Column Names

```svelte ``` ### Groups - Accordion #### Without subtotals ```orders select state, category, item, count(1) as orders, sum(sales) as sales, if(random() > 0.3, 1, -1) * 0.1 * random() as growth from needful_things.orders group by all limit 25 ```

```svelte ``` #### With Subtotals

```svelte ``` #### Closed by Default

```svelte ``` #### With Configured Columns

```svelte ``` ### Groups - Section #### Without subtotals

```svelte ``` #### With Subtotals

```svelte ``` #### With Configured Columns

```svelte ``` ### Column Groups ```sql countries SELECT 'United States' as country, 'North America' as continent, 22996 as gdp_usd, 0.017 as gdp_growth, 0.025 as interest_rate, 0.085 as inflation_rate, 0.037 as jobless_rate, -16.7 as gov_budget, 137.2 as debt_to_gdp, -3.6 as current_account, 332.4 as population UNION ALL SELECT 'China', 'Asia', 17734, 0.004, 0.0365, 0.027, 0.054, -3.7, 66.8, 1.8, 1412.6 UNION ALL SELECT 'Japan', 'Asia', 4937, 0.002, -0.001, 0.026, 0.026, -12.6, 266.2, 3.2, 125.31 UNION ALL SELECT 'Germany', 'Europe', 4223, 0.017, 0.005, 0.079, 0.055, -3.7, 69.3, 7.4, 83.16 UNION ALL SELECT 'United Kingdom', 'Europe', 3187, 0.029, 0.0175, 0.101, 0.038, -6, 95.9, -2.6, 67.53 UNION ALL SELECT 'India', 'Asia', 3173, 0.135, 0.054, 0.0671, 0.078, -9.4, 73.95, -1.7, 1380 UNION ALL SELECT 'France', 'Europe', 2937, 0.042, 0.005, 0.058, 0.074, -6.5, 112.9, 0.4, 67.63 UNION ALL SELECT 'Italy', 'Europe', 2100, 0.047, 0.005, 0.084, 0.079, -7.2, 150.8, 2.5, 59.24 UNION ALL SELECT 'Canada', 'North America', 1991, 0.029, 0.025, 0.076, 0.049, -4.7, 117.8, 0.1, 38.44 UNION ALL SELECT 'South Korea', 'Asia', 1799, 0.029, 0.025, 0.057, 0.029, -6.1, 42.6, 3.5, 51.74 UNION ALL SELECT 'Russia', 'Europe', 1776, -0.04, 0.08, 0.151, 0.039, 0.8, 18.2, 6.8, 145.55 UNION ALL SELECT 'Brazil', 'South America', 1609, 0.032, 0.1375, 0.1007, 0.091, -4.5, 80.27, -1.8, 213.32 ```

```svelte ``` ### Wrap Titles

```svelte ``` # DataTable ## Options Query name, wrapped in curly braces Number of rows to show in the table before paginating results. Use `rows=all` to show all rows in the table. Background color of the header row Font color of the header row Show a total row at the bottom of the table, defaults to sum of all numeric columns Background color of the total row Font color of the total row Turns on or off row index numbers Turns on or off borders at the bottom of each row Shades every second row in light grey Background color of the table Enable sort for each column - click the column title to sort Column to sort by on initial page load. Sort direction is asc if unspecified. Can only sort by one column using this prop. If you need multi-column sort, use the order by clause in your sql in combination with this prop. Add a search bar to the top of your table Enable download data button below the table on hover Enable auto-formatting of column titles. Turn off to show raw SQL column names Wrap column titles Enable a more compact table view that allows more content vertically and horizontally Makes 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 Whether to show the column supplied to the `link` prop Helper 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. 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. 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.). ### Groups Groups allow you to create sections within your table, increasing the density of the content you're displaying. Groups are currently limited to 1 level, but will be expanded in future versions. Column to use to create groups. Note that groups are currently limited to a single group column. How the groups are shown in the table. Can be accordion (expand/collapse) or section (group column values are merged across rows) Whether to show aggregated totals for the groups Specify an override format to use in the subtotal row ([see available formats](/core-concepts/formatting)). Custom strings or values are unformatted by default. [groupType=accordion] Whether to show the accordions as open on page load [groupType=accordion] Background color for the accordion row [groupType=section] Background color for the subtotal row [groupType=section] Font color for the subtotal row [groupType=section] Where the group label will appear in its cell # 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 Column id (from SQL query) Override title of column Align column text Format the values in the column ([see available formats](/core-concepts/formatting)) Column to use to format values in this column. This is used to achieve different value formats by row. The fmtColumn should contain strings of format codes - either Evidence built-in formats or Excel codes. Specify an aggregation function to use for the total row. Accepts predefined functions, custom strings or values Specify an override format to use in the total row ([see available formats](/core-concepts/formatting)). Custom strings or values are unformatted by default. Column 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. Wrap column text Wrap column title Lets you specify how to treat the content within a column. See below for contentType-specific options. Group name to display above a group of columns. Columns with the same group name will get a shared header above them Conditionally sets the font color to red based on whether the selected value is less than 0 ### Images `contentType=image` Height of image in pixels Width of image in pixels Alt text for image ### Links `contentType=link` Text to display for link Whether to open link in new tab ### Deltas `contentType=delta` Whether to show the up/down delta arrow symbol If present, negative comparison values appear in green, and positive values appear in red. Whether to show the delta value. Set this to false to show only the delta arrow indicator. Start of the range for 'neutral' values, which appear in grey font with a dash instead of an up/down arrow. By default, neutral is not applied to any values. End of the range for 'neutral' values, which appear in grey font with a dash instead of an up/down arrow. By default, neutral is not applied to any values. Whether to display the delta as a 'chip', with a background color and border. ### Sparklines `contentType=sparkline` `contentType=sparkarea` `contentType=sparkbar` Column within an array cell to use as the x-axis for the spark viz. Arrays can be created inside a query using the `array_agg()` function from DuckDB Column within an array cell to use as the y-axis for the spark viz. Arrays can be created inside a query using the `array_agg()` function from DuckDB Whether to truncate the y-axis Height of the spark viz. Making the viz taller will increase the height of the full table row Width of the spark viz Color of the spark viz ### Bar Chart Column `contentType=bar` Color of the bars. Affects positive bars only. See `negativeBarColor` to change color of negative bars Color of negative bars Whether to hide the data labels on the bars Background color for bar chart ### Conditional Formatting (Color Scales) `contentType=colorscale` Color to use for the scale Set a minimum for the scale. Any values below that minimum will appear in the lowest color on the scale Set a midpoint for the scale Set a maximum for the scale. Any values above that maximum will appear in the highest color on the scale Array of numbers to use as breakpoints for each color in your color scale. Should line up with the colors you provide in `colorScale` Column to use to define the color scale range. Values in this column will have their cell color determined by the value in the scaleColumn ### HTML `contentType=html` To apply styling to HTML tags, you will need to add the `class=markdown` attribute **to the HTML tag in your column**. This will apply the same styling as the markdown renderer. E.g., `Code` --- evidence/sites/docs/pages/components/custom-echarts/index.md --- --- sidebar_position: 98 title: Custom ECharts --- Our chart library is based on [ECharts](https://echarts.apache.org/examples/en/index.html), a powerful and flexible open source JavaScript chart library. We use many of the features in ECharts, and combine them with custom data transformation, logic, and theming. ## `` Component If you would like to create a fully custom chart, you can use our built-in `` component. This component accepts a JavaScript object containing a chart configuration. To test this out, you can find an example on the [ECharts example page](https://echarts.apache.org/examples/en/index.html) and paste the option object into the Evidence `` component. This will let you create a chart that matches Evidence theming, but gives you access to the [full suite](https://echarts.apache.org/en/option.html#title) of ECharts features. The downside of this approach is that `` requires data to be included in the configuration object, which can be difficult depending on the type of chart you need. If you would like to use specialized ECharts features, but retain the data management you get with Evidence charts, we recommend building a [mixed-type chart](/components/mixed-type-charts) and passing in an `options` object for the specific features you need. ## How to Build the Configuration To create a JavaScript object in an Evidence markdown page, you need to add a `<script>` tag. Any objects or variables you create in that script tag are then accessible by the rest of your page using curly braces. For example, if you create a variable named `myVar`, you can show the contents of that variable in your markdown using `{myVar}`. ## Examples ### Simple Treemap [Link to ECharts example](https://echarts.apache.org/examples/en/editor.html?c=treemap-simple) ECharts requires the data object to have a specific format. For example in the treemap chart show below it expects the columns to be called “name” and “value”. The `test_data` query in the code below renames the fields from the original query so ECharts can use them.

```sql sales_by_country select 'Canada' as country, 100 as sales union all select 'US' as country, 250 as sales union all select 'UK' as country, 130 as sales union all select 'Australia' as country, 95 as sales ``` ```sql test_data select country as name, sales as value from ${sales_by_country} ```

````markdown ```sql sales_by_country select 'Canada' as country, 100 as sales union all select 'US' as country, 250 as sales union all select 'UK' as country, 130 as sales union all select 'Australia' as country, 95 as sales ``` ```sql test_data select country as name, sales as value from ${sales_by_country} ``` ```` ### Funnel Chart [Link to ECharts example](https://echarts.apache.org/examples/en/editor.html?c=funnel) ECharts requires the data object to have a specific format. For example in the funnel chart show below it expects the columns to be called “name” and “value”. The `funnel_data` query in the code below renames the fields from the original query so ECharts can use them.

```sql funnel_stages select 'Emailed' as stage, 129 as count union all select 'Meeting' as stage, 86 as count union all select 'Proposal' as stage, 65 as count union all select 'Signed' as stage, 44 as count ``` ```sql funnel_data select stage as name, count as value from ${funnel_stages} ```

````markdown ```sql funnel_stages select 'Emailed' as stage, 129 as count union all select 'Meeting' as stage, 86 as count union all select 'Proposal' as stage, 65 as count union all select 'Signed' as stage, 44 as count ``` ```sql funnel_data select stage as name, count as value from ${funnel_stages} ``` ```` ### Pie Chart [Link to ECharts example](https://echarts.apache.org/examples/en/editor.html?c=pie-simple) ECharts requires the data object to have a specific format. For example in the pie chart show below it expects the columns to be called “name” and “value”. The `pie_data` query in the code below renames the fields from the original query so ECharts can use them.

```sql pie_query select 'Apple' as pie, 60 as count union all select 'Blueberry' as pie, 70 as count union all select 'Cherry' as pie, 40 as count union all select 'Pecan' as pie, 35 as count ``` ```sql pie_data select pie as name, count as value from ${pie_query} ```

````markdown ```sql pie_query select 'Apple' as pie, 60 as count union all select 'Blueberry' as pie, 70 as count union all select 'Cherry' as pie, 40 as count union all select 'Pecan' as pie, 35 as count ``` ```sql pie_data select pie as name, count as value from ${pie_query} ``` ```` ### Donut Chart [Link to ECharts example](https://echarts.apache.org/examples/en/editor.html?c=pie-doughnut) ECharts requires the data object to have a specific format. For example in the donut chart show below it expects the columns to be called “name” and “value”. The `donut_data` query in the code below renames the fields from the original query so ECharts can use them.

```sql donut_query select 'Glazed' as donut, 213 as count union all select 'Cruller' as donut, 442 as count union all select 'Jelly-filled' as donut, 321 as count union all select 'Cream-filled' as donut, 350 as count ``` ```sql donut_data select donut as name, count as value from ${donut_query} ```

````markdown ```sql donut_query select 'Glazed' as donut, 213 as count union all select 'Cruller' as donut, 442 as count union all select 'Jelly-filled' as donut, 321 as count union all select 'Cream-filled' as donut, 350 as count ``` ```sql donut_data select donut as name, count as value from ${donut_query} ``` ```` ### Advanced Chart [Link to ECharts example](https://echarts.apache.org/examples/en/editor.html?c=scatter-anscombe-quartet)

```markdown <script> const dataAll = [ [ [10.0, 8.04], [8.0, 6.95], [13.0, 7.58], [9.0, 8.81], [11.0, 8.33], [14.0, 9.96], [6.0, 7.24], [4.0, 4.26], [12.0, 10.84], [7.0, 4.82], [5.0, 5.68] ], [ [10.0, 9.14], [8.0, 8.14], [13.0, 8.74], [9.0, 8.77], [11.0, 9.26], [14.0, 8.1], [6.0, 6.13], [4.0, 3.1], [12.0, 9.13], [7.0, 7.26], [5.0, 4.74] ], [ [10.0, 7.46], [8.0, 6.77], [13.0, 12.74], [9.0, 7.11], [11.0, 7.81], [14.0, 8.84], [6.0, 6.08], [4.0, 5.39], [12.0, 8.15], [7.0, 6.42], [5.0, 5.73] ], [ [8.0, 6.58], [8.0, 5.76], [8.0, 7.71], [8.0, 8.84], [8.0, 8.47], [8.0, 7.04], [8.0, 5.25], [19.0, 12.5], [8.0, 5.56], [8.0, 7.91], [8.0, 6.89] ] ]; const markLineOpt = { animation: false, label: { formatter: 'y = 0.5 * x + 3', align: 'right' }, lineStyle: { type: 'solid' }, tooltip: { formatter: 'y = 0.5 * x + 3' }, data: [ [ { coord: [0, 3], symbol: 'none' }, { coord: [20, 13], symbol: 'none' } ] ] }; let options = { title: { text: "Anscombe's quartet", left: 'center', top: 0 }, grid: [ { left: '7%', top: '7%', width: '38%', height: '38%' }, { right: '7%', top: '7%', width: '38%', height: '38%' }, { left: '7%', bottom: '7%', width: '38%', height: '38%' }, { right: '7%', bottom: '7%', width: '38%', height: '38%' } ], tooltip: { formatter: 'Group {a}: ({c})' }, xAxis: [ { gridIndex: 0, min: 0, max: 20 }, { gridIndex: 1, min: 0, max: 20 }, { gridIndex: 2, min: 0, max: 20 }, { gridIndex: 3, min: 0, max: 20 } ], yAxis: [ { gridIndex: 0, min: 0, max: 15 }, { gridIndex: 1, min: 0, max: 15 }, { gridIndex: 2, min: 0, max: 15 }, { gridIndex: 3, min: 0, max: 15 } ], toolbox: { show: true, feature: { saveAsImage: { show: true } } }, series: [ { name: 'I', type: 'scatter', xAxisIndex: 0, yAxisIndex: 0, data: dataAll[0], markLine: markLineOpt }, { name: 'II', type: 'scatter', xAxisIndex: 1, yAxisIndex: 1, data: dataAll[1], markLine: markLineOpt }, { name: 'III', type: 'scatter', xAxisIndex: 2, yAxisIndex: 2, data: dataAll[2], markLine: markLineOpt }, { name: 'IV', type: 'scatter', xAxisIndex: 3, yAxisIndex: 3, data: dataAll[3], markLine: markLineOpt } ] }; </script> ``` --- evidence/sites/docs/pages/components/histogram/index.md --- --- title: Histogram sidebar_position: 1 --- ```sql orders select * from needful_things.orders limit 1000 ``` ```sql orders_week select * from needful_things.orders limit 10000 ```

```markdown ``` ## Examples ### Histogram

```markdown ``` ## Options ### Data Query name, wrapped in curly braces Column which contains the data you want to summarize 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. 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.). ### Formatting & Styling Format to use for x column ([see available formats](/core-concepts/formatting)) Color to override default series color % of the full color that should be rendered, with remainder being transparent Array of custom colours to use for the chart. E.g., `{['#cf0d06','#eb5752','#e88a87']}` ### Axes Name to show under x-axis. If 'true', formatted column name is used. Only works with swapXY=false Name to show beside y-axis. If 'true', formatted column name is used. Turns on/off gridlines extending from x-axis tick marks (vertical lines when swapXY=false) Turns on/off gridlines extending from y-axis tick marks (horizontal lines when swapXY=false) Turns on/off value labels on the x-axis Turns on/off value labels on the y-axis Turns on/off thick axis line (line appears at y=0) Turns on/off thick axis line (line appears directly alongside the y-axis labels) Turns on/off tick marks for each of the x-axis labels Turns on/off tick marks for each of the y-axis labels Starting value for the y-axis Maximum value for the y-axis ### Chart Chart title. Appears at top left of chart. Chart subtitle. Appears just under title. Turns legend on or off. Legend appears at top center of chart. Minimum height of the chart area (excl. header and footer) in pixels. Adjusting the height affects all viewport sizes and may impact the mobile UX. Which chart renderer type (canvas or SVG) to use. See ECharts' [documentation on renderers](https://echarts.apache.org/handbook/en/best-practices/canvas-vs-svg/). ### Custom Echarts Options Custom Echarts options to override the default options. See [reference page](/components/echarts-options/) for available options. Custom Echarts options to override the default options for all series in the chart. This loops through the series to apply the settings rather than having to specify every series manually using `echartsOptions` See [reference page](/components/echarts-options/) for available options. Helper prop for custom chart development - inserts a code block with the current echarts config onto the page so you can see the options used and debug your custom options ### Interactivity Group name to connect this chart to other charts for synchronized tooltip hovering. Charts with the same `connectGroup` name will become connected ## Annotations Histograms can include [annotations](/components/annotations) using the `ReferenceLine` and `ReferenceArea` components. These components are used within a chart component like so: ```html ``` --- evidence/sites/docs/pages/components/delta/index.md --- --- sidebar_position: 1 title: Delta --- ```sql growth select 0.366 as positive, -0.366 as negative ```

```markdown ``` ## Examples ### Value Types #### Positive & Negative ```markdown ``` #### Neutral

```markdown ``` #### Negative

```markdown ``` #### Neutral* *Values are not defined as neutral until you define a range using the `neutralMin` and `neutralMax` props

```markdown ``` ### Chips #### Positive & Negative ```markdown ``` #### Neutral

````markdown ```` #### Negative

````markdown ```` #### Neutral* *Values are not defined as neutral until you define a range using the `neutralMin` and `neutralMax` props

```markdown ``` ### Symbol Position #### Symbol on Left

```html ``` #### Symbol on Left in Chip

```html ``` ## Options Query name, wrapped in curly braces Column to pull values from Row number to display. 0 is the first row. Pass a specific value to the component (e.g., value=100). Overridden by the data/column props. Format to use for the value ([see available formats](/core-concepts/formatting)) If true, negative comparison values appear in green, and positive values appear in red. Whether to show the up/down delta arrow symbol Whether to show the value. Set this to false to show only the delta arrow indicator. Text to display after the delta symbol and value Start of the range for 'neutral' values, which appear in grey font with a dash instead of an up/down arrow. By default, neutral is not applied to any values. End of the range for 'neutral' values, which appear in grey font with a dash instead of an up/down arrow. By default, neutral is not applied to any values. Whether to display the delta as a 'chip', with a background color and border. Whether to display the delta symbol to the left or right of the value 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. 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.). --- evidence/sites/docs/pages/components/point-map/index.md --- --- title: Point Map sidebar_position: 1 ---

```html ``` ```sql la_locations select *, 'https://www.google.com/search?q=' || point_name as link_col from la_locations ``` ## Examples ### Custom Basemap You can add a different basemap by passing in a basemap URL. You can find examples here: https://leaflet-extras.github.io/leaflet-providers/preview/

**Note:** you need to wrap the url in curly braces and backticks to avoid the curly braces in the URL being read as variables on your page ```svelte ``` ### Custom Tooltip #### `tooltipType=hover`

```svelte ``` #### With clickable link and `tooltipType=click`

```svelte ``` ### Custom Color Palette

```svelte ``` ### Custom Styling

```svelte ``` ### Link Drilldown Pass in a `link` column to enable navigation on click of the point. These can be absolute or relative URLs

```svelte ``` ### Use Map as Input Use the `name` prop to set an input name for the map - when a point is clicked, it will set the input value to that row of data

```svelte ``` *Click a point on the map to see the input value get updated:* #### Selected value for `{inputs.my_point_map}`:

{JSON.stringify(inputs.my_point_map, null, 2)}

#### Selected value for `{inputs.my_point_map.point_name}`: {inputs.my_point_map.point_name} ```filtered_locations select * from ${la_locations} where point_name = '${inputs.my_point_map.point_name}' OR '${inputs.my_point_map.point_name}' = 'true' ``` #### Filtered Data ### Legends ```grouped_locations SELECT *, CASE WHEN id BETWEEN 0 AND 4 THEN 'Hotels' WHEN id BETWEEN 5 AND 9 THEN 'Restaurants' WHEN id BETWEEN 10 AND 14 THEN 'Golf Courses' WHEN id BETWEEN 15 AND 19 THEN 'Shops' WHEN id BETWEEN 20 AND 24 THEN 'Bars' WHEN id BETWEEN 25 AND 29 THEN 'Entertainment' WHEN id BETWEEN 30 AND 34 THEN 'Banks' END AS Category FROM la_locations ``` #### Categorical Legend

```svelte ``` #### Custom Colors Set custom legend colors using the `colorPalette` prop to match the number of categories; excess categorical options will default to standard colors.

```svelte ``` #### Scalar Legend

```svelte ``` #### Custom Colors Define scalar legend colors using the `colorPalette` prop, allowing specified colors to create a gradient based on the range of values.

```svelte ``` ## Options ### Points Query result, referenced using curly braces Column that determines the value displayed at each point. Format string for displaying the value. Column containing the names/labels of the points - by default, this is shown as the title of the tooltip. ### Color Scale Array of colors used for theming the points based on data Minimum value to use for the color scale. Maximum value to use for the color scale. ### Legend Appends a categorical or scalar legend to the map Determines the legend's position on the map, with options provided ### Interactivity URL to navigate to when a point is clicked. Input name. Can be referenced on your page with `{inputs.my_input_name}` ### Styling Color for the points. Use when you want all points to be the same color. Size of the points Width of the border around each point. Color of the border around each point. Opacity of the points. ### Selected State When point is selected: Color for the points. Use when you want all points to be the same color. When point is selected: Width of the border around each point. When point is selected: Color of the border around each point. When point is selected: Opacity of the points. ### Tooltips Whether to show tooltips Determines whether tooltips are activated by hover or click. CSS class applied to the tooltip content. You can pass Tailwind classes into this prop to custom-style the tooltip Configuration for tooltips associated with each area. See below example for format #### `tooltip` example: ```javascript tooltip={[ {id: 'zip_code', fmt: 'id', showColumnName: false, valueClass: 'text-xl font-semibold'}, {id: 'sales', fmt: 'eur', fieldClass: 'text-[grey]', valueClass: 'text-[green]'}, {id: 'zip_code', showColumnName: false, contentType: 'link', linkLabel: 'Click here', valueClass: 'font-bold mt-1'} ]} ``` #### All options available in `tooltip`: - `id`: column ID - `title`: custom string to use as title of field - `fmt`: format to use for value - `showColumnName`: whether to show the column name. If `false`, only the value will be shown - `contentType`: currently can only be "link" - `linkLabel`: text to show for a link when contentType="link" - `formatColumnTitle`: whether to automatically uppercase the first letter of the title. Only applies when `title` not passed explicitly - `valueClass`: custom Tailwind classes to style the values - `fieldClass`: custom Tailwind classes to style the column names ### Base Map URL template for the basemap tiles. Attribution text to display on the map (e.g., "© OpenStreetMap contributors"). Optional title displayed above the map. Starting latitude for the map center. Starting longitude for the map center. Initial zoom level of the map. Height of the map in pixels. --- evidence/sites/docs/pages/components/button-group/index.md --- --- title: Button Group sidebar_position: 1 queries: - categories.sql --- Creates a group of single-select buttons for quick filtering To see how to filter a query using a Button Group, see [Filters](/core-concepts/filters). ## Examples ### Button Group using Options from a Query

Selected: {inputs.category_picker}

```markdown Selected: {inputs.category_picker} ``` ### With a Title

Selected: {inputs.category_selector}

```markdown Selected: {inputs.category_selector} ``` ### With a Default Value

Selected: {inputs.selected_button1}

````markdown Selected: {inputs.selected_button1} ```` ### With Hardcoded Options

Selected: {inputs.hardcoded_options}

````markdown Selected: {inputs.hardcoded_options} ```` ### With Hardcoded Options and Default Value

Selected: {inputs.hardcoded_options_default}

````markdown Selected: {inputs.hardcoded_options_default} ```` ### Alternative Labels

Selected: {inputs.alternative_labels_selector}

````markdown Selected: {inputs.alternative_labels_selector} ```` ### Filtering a Query ```sql filtered_query select category, item, sum(sales) as total_sales from needful_things.orders where category like '${inputs.category_button_group}' group by all ```

````markdown ```` ### Style Buttons as Tabs

Selected: {inputs.buttons_as_tabs}

```markdown Selected: {inputs.buttons_as_tabs} ``` ### Style Buttons as Tabs: With Hardcoded Options

Selected: {inputs.button_tabs_hardcoded_options}

````markdown Selected: {inputs.button_tabs_hardcoded_options} ```` # ButtonGroup ## Options # ButtonGroupItem The ButtonGroupItem component can be used to manually add options to a button group. This is useful if you want to add a default option, or if you want to add options that are not in a query. ## Options --- evidence/sites/docs/pages/components/base-map/index.md --- --- title: Base Map sidebar_position: 1 ---

```html ``` ```sql la_zip_sales select *, 'https://www.google.com/search?q=' || zip_code as link_col from la_zip_sales where zip_code <> 90704 ``` ```sql la_locations select *, 'https://www.google.com/search?q=' || point_name as link_col from la_locations ``` ## Overview The BaseMap component provides a flexible and extensible way to create maps with multiple layers. This component serves as the foundation for AreaMap, PointMap, and BubbleMap. Within BaseMap, you can add layers using the following components: - `` - `` - `` ## Examples See the pages for [Area Map](/components/area-map), [Point Map](/components/point-map), and [Bubble Map](/components/bubble-map) for examples specific to those layers. The same options can be applied to the layer components within BaseMap. ### Adding Multiple Layers

```svelte ``` ### Custom Basemap You can add a different basemap by passing in a basemap URL. You can find examples here: https://leaflet-extras.github.io/leaflet-providers/preview/

```svelte ``` ### Custom Tooltip #### `tooltipType=hover`

```svelte ``` #### With clickable link and `tooltipType=click`

```svelte ``` ## Map Resources ```sql all_geojson_urls select * exclude(properties) from geojson_urls order by scale, category, file ``` ```sql useful_geojson_urls select * from ${all_geojson_urls} where category in ('political_countries', 'political_states') or file ilike 'populated_places%' order by scale desc, category, file ``` Below are a selection of publically available GeoJSON files that may be useful for mapping. These are from the [Natural Earth Data](https://www.naturalearthdata.com/) project, and hosted by [GeoJSON.xyz](https://geojson.xyz/). ### Country, State, and City Locations

## Base Map Options URL template for the basemap tiles. Attribution text to display on the map (e.g., "© OpenStreetMap contributors"). Optional title displayed above the map. Starting latitude for the map center. Starting longitude for the map center. Initial zoom level of the map. Height of the map in pixels. ## Layer Options ### Areas Use the `` component to add an area layer Query result, referenced using curly braces. Path to source geoJSON data from - can be a URL (see [Map Resources](#map-resources)) or a file in your project. If the file is in your `static` directory in the root of your project, reference it as `geoJsonUrl="/your_file.geojson"` Column in the data that specifies the area each row belongs to. Property in the GeoJSON that uniquely identifies each feature. Column that determines the value displayed for each area (used for color scale). Format string for displaying the value. ### Points Use the `` component to add an area layer Query result, referenced using curly braces. Column containing latitude values. Column containing longitude values. Column that determines the value displayed at each point. Format string for displaying the value. Column containing the names/labels of the points - by default, this is shown as the title of the tooltip. ### Bubbles Use the `` component to add an area layer Query result, referenced using curly braces. Column containing latitude values. Column containing longitude values. Column that determines the size displayed for each point. Format string for displaying the size value in tooltips. Maximum size of the bubbles. Column that determines the value displayed at each point (used for color scale). Format string for displaying the value. Column containing the names/labels of the points - by default, this is shown as the title of the tooltip. Specifies the type of pane where the bubbles will be rendered. Represents the z-index value for the pane, controlling its stacking order relative to other panes (higher values are on top, e.g., z=2 is above z=1). ### Common Layer Options #### Color Scale Array of colors used for theming the points or areas based on data. Minimum value to use for the color scale. Maximum value to use for the color scale. #### Interactivity URL to navigate to when a point or area is clicked. Input name. Can be referenced on your page with {inputs.my_input_name}. #### Styling Color for the points or areas. Use when you want all points or areas to be the same color. Width of the border around each point or area. Color of the border around each point or area. Opacity of the points or areas. #### Selected State When point or area is selected: Color for the points or areas. When point or area is selected: Width of the border around each point or area. When point or area is selected: Color of the border around each point or area. When point or area is selected: Opacity of the points or areas. #### Tooltips Whether to show tooltips. Determines whether tooltips are activated by hover or click. CSS class applied to the tooltip content. You can pass Tailwind classes into this prop to custom-style the tooltip. Configuration for tooltips associated with each area. See below example for format #### `tooltip` example: ```javascript tooltip={[ {id: 'zip_code', fmt: 'id', showColumnName: false, valueClass: 'text-xl font-semibold'}, {id: 'sales', fmt: 'eur', fieldClass: 'text-[grey]', valueClass: 'text-[green]'}, {id: 'zip_code', showColumnName: false, contentType: 'link', linkLabel: 'Click here', valueClass: 'font-bold mt-1'} ]} ``` #### All options available in `tooltip`: - `id`: column ID - `title`: custom string to use as title of field - `fmt`: format to use for value - `showColumnName`: whether to show the column name. If `false`, only the value will be shown - `contentType`: currently can only be "link" - `linkLabel`: text to show for a link when contentType="link" - `formatColumnTitle`: whether to automatically uppercase the first letter of the title. Only applies when `title` not passed explicitly - `valueClass`: custom Tailwind classes to style the values - `fieldClass`: custom Tailwind classes to style the column names --- evidence/sites/docs/pages/components/calendar-heatmap/index.md --- --- title: Calendar Heatmap sidebar_position: 1 queries: - orders_by_day.sql - orders_by_day_2021.sql ---

```markdown ``` ## Examples ### Multi-Year

```markdown ``` ### Custom Color Scale

```markdown ``` ### Without Year Label

```markdown ``` ## Options ### Data ### Formatting & Styling ### Chart ### Custom Echarts Options ### Interactivity --- evidence/sites/docs/pages/components/custom-components/component-queries.md --- # Component Queries Component queries allow you to run SQL queries in your component code. Component queries transform how we build data visualizations. Instead of passing data down through props from parent pages, components become self-contained units that can request exactly what they need. This independence makes components more reusable and easier to maintain, as all the logic for both fetching and displaying data lives in one place. ## Static Queries Static queries are "static" because the SQL string they run cannot change throughout the component's lifecycle. They are defined once when your component is created, and are executed when `QueryLoad` is mounted. Here's how to create a component that fetches and displays information about tables in your database: ```html title="components/TableList.svelte" <script> import { buildQuery } from '@evidence-dev/component-utilities/buildQuery'; import { QueryLoad } from '@evidence-dev/core-components'; const query = buildQuery( 'SELECT * FROM information_schema.tables', );

{table.table_name}

``` ### The Query Loader The `QueryLoad` component manages the entire lifecycle of your query execution. It handles: - Executing your query against DuckDB - Managing loading states - Handling any errors that occur - Delivering results to your component ```html ``` The `let:loaded` directive creates a new variable containing your query results. Using a descriptive name (like `tableData` or `salesMetrics`) makes your code more maintainable than the generic `loaded`. ## Dynamic Queries For queries that change based on user input or component state, you need dynamic queries. This allows you to create interactive components. Here's an example that lets users control how many rows to display: ```html title="components/DynamicTableList.svelte" <script> import { QueryLoad } from '@evidence-dev/core-components'; import { getQueryFunction } from '@evidence-dev/component-utilities/buildQuery'; import { Query } from '@evidence-dev/sdk/usql'; // This will hold our current query result let query; // Create a reactive query function const queryFunction = Query.createReactive({ execFn: getQueryFunction(), callback: v => query = v }); // These values will control our query let limit = 10; let schemaName = 'public'; // This reactive statement runs whenever limit or schemaName change $: queryFunction(` SELECT * FROM information_schema.tables WHERE table_schema = '${schemaName}' LIMIT ${limit} `);

Rows to show: Schema:

{table.table_name}

``` Let's understand how this works: ### Query State Management 1. First, we create a variable to hold our query result: ```javascript let query; ``` This will be updated every time our query executes with new parameters. 2. Next, we create a reactive query function: ```javascript const queryFunction = Query.createReactive({ execFn: getQueryFunction(), callback: v => query = v }); ``` This sets up an environment that can execute queries and update our component's state. 3. Finally, we use Svelte's reactive declarations to run our query: ```javascript $: queryFunction(`SELECT * FROM ... LIMIT ${limit}`); ``` The `$:` syntax tells Svelte to re-run this statement whenever `limit` changes, creating a connection between your component's state and your query. ## Error Handling When working with queries, things can sometimes go wrong. Maybe a query is malformed, or perhaps it's trying to access a table that doesn't exist. The `QueryLoad` component helps you handle these situations gracefully through its error slot: ```html

Unable to load data

{error.message}

Please check your query and try again.

{table.table_name}

``` When a query fails, Evidence: 1. Captures the error information 2. Prevents the main content from rendering 3. Makes the error details available through `let:error` 4. Displays your error handling content --- evidence/sites/docs/pages/components/custom-components/index.md --- --- sidebar_position: 99 title: Custom Components --- Custom components allow you to extend the functionality of Evidence, as well as to make your code more reusable. In Evidence, you can build your own components and use them anywhere in your app. This is made possible through Svelte, the JavaScript framework Evidence is built on. These components can include the charts used for visualization, custom components created completely from scratch, or adaptations of existing UI components such as the header, sidebar, menu, etc. [Evidence Labs](https://labs.evidence.dev) contains several good examples of custom components. Below is a **short guide** on building a simple component in Evidence. For a fuller guide, Svelte offers a really great interactive tutorial that you can complete in your browser in about an hour: [Svelte Tutorial](https://svelte.dev/tutorial/basics) **Built a great component?** Let us know in our [Slack community](https://slack.evidence.dev)! We'd love to see what you've built, and may add generally applicable components to Evidence Labs, or the Evidence component library! ## Example custom component If you were creating a component called ``, which included some text and a BarChart, to use in `index.md`, you could do so like this: Add a folder called `components/` in the root of your project. This is where Evidence looks for your Svelte components: ### Folder structure ```bash . |-- pages/ | `-- index.md `-- components/ `-- Hello.svelte ``` `Hello.svelte` is your component. Add the following code to these two files: ### File contents ````html title="index.md" ```sql sales_by_country select 'Canada' as country, 100 as sales_usd union all select 'USA' as country, 200 as sales_usd union all select 'UK' as country, 300 as sales_usd ``` ```` ```html title="Hello.svelte" <script> export let myData; import { BarChart } from '@evidence-dev/core-components'; </script>

Here is a BarChart in a Component, with some accompanying text. Components stored in the /components/ folder will be included in your app.

``` ## Building your own component: Checklist If you're building a component, here are some things to keep in mind. In your markdown file: 1. **Pass any data as props** if you need to access query results in the component In the custom component: 1. **Use Svelte (HTML + extra features) syntax** in this component - it will not support Markdown 1. **Use the `/components/` folder** for your .svelte files 1. **`export` any props you want to use** in the component 1. **Import any [Evidence components](https://github.com/evidence-dev/evidence/tree/main/sites/example-project/src/components)** you want to use in the custom component ## Optional: Publishing Your Components as a Plugin If you have built custom components that you would like other Evidence users to be able to use in their apps, you can publish them as an Evidence plugin. See the [Plugin section](/plugins/create-component-plugin/) for more details. ## Utility Functions Evidence provides a collection of helpful utility functions to use within custom components, for things like error handling, data manipulation, and value formatting. To use these utilities, you must import them explicitly in the script tag portion of your component. The import line for each utlity function is included for reference below: ### Error Handling #### checkInputs `checkInputs(data, reqCols, optCols)` Accepts a dataset and list of columns, and returns an error if the dataset is empty, required columns are missing, or referenced columns do not exist in the data ```javascript import checkInputs from '@evidence-dev/component-utilities/checkInputs'; ``` - `data`: the query result you need to check - `reqCols`: a list of columns that are required for your component (e.g., x or y for a chart) - `optCols`: a list of optional columns
#### ErrorChart `` A component used to display an error state on the page ```javascript import { ErrorChart } from '@evidence-dev/core-components'; ``` - `error`: the error message to display - `chartType`: the title that appears at the top of the error component
### Data Manipulation #### getDistinctValues `getDistinctValues(data, column)` Returns an array of distinct values from a specified column in a dataset ```javascript import getDistinctValues from '@evidence-dev/component-utilities/getDistinctValues'; ``` - `data`: query result to pull the values from - `column`: name of column to use
#### getDistinctCount `getDistinctCount(data, column)` Returns the count of distinct values in a column ```javascript import getDistinctCount from '@evidence-dev/component-utilities/getDistinctCount'; ``` - `data`: query result to pull the values from - `column`: name of column to use
#### getSortedData `getSortedData(data, col, isAsc)` Returns the original dataset, sorted by the specific column and direction ```javascript import getSortedData from '@evidence-dev/component-utilities/getSortedData'; ``` - `data`: query result to pull the values from - `col`: name of column to sort - `isAsc`: if true, will sort ascending; otherwise, descending
#### getColumnSummary `getColumnSummary(data, returnType = "object")` Returns an object with information about each column (title, min, max, format, etc.) ```javascript import getColumnSummary from '@evidence-dev/component-utilities/getColumnSummary'; ``` - `data`: query result to summarize - `returnType`: "object" or "array"
#### getCompletedData `getCompletedData(data, x, y, series, nullsZero = false, fillX = false)` Returns the original dataset with rows filled in as needed to complete a continuous number series ```javascript import getCompletedData from '@evidence-dev/component-utilities/getCompletedData'; ``` - `data`: query result which requires completed data - `x`: name of column for x-axis - `y`: name of column for y-axis - `series`: name of column for series - `nullsZero`: if true, will treat nulls as zeroes; otherwise, will leave as nulls - `fillX`: if true, will find the smallest increment in the x-axis values and create rows as needed to create a continous series
### Value & Label Formatting #### formatValue `formatValue(value, columnFormat = undefined, columnUnitSummary = undefined)` Returns a formatted value ```javascript import { formatValue } from '@evidence-dev/component-utilities/formatting'; ``` - `value`: value to format - `columnFormat`: a format object for column being formatted (can be obtained from the `getColumnSummary` function) - `columnUnitSummary`: an object containing the extents of the column, used for unit summary formatting like "M" or "B" (can be obtained from the `getColumnSummary` function)
#### fmt `fmt(value, format)` Simpler version of the `formatValue` function which does not require a format object ```javascript import { fmt } from '@evidence-dev/component-utilities/formatting'; ``` - `value`: value to be formatted - `format`: a string representing a format tag name or an Excel-style format code
#### formatTitle `formatTitle(column, columnFormat)` Returns a formatted column title (with proper letter casing) ```javascript import formatTitle from '@evidence-dev/component-utilities/formatTitle'; ``` - `column`: name of column to be formatted - `columnFormat`: a format object for column being formatted (can be obtained from the `getColumnSummary` function) ## Adding Queries Custom components can execute queries rather than requiring data to be passed to them. See [component queries](./component-queries) for details --- evidence/sites/docs/pages/components/us-map/index.md --- --- title: US Map sidebar_position: 1 queries: - state_population.sql ---

```html ``` ## Examples ### Color Scales `colorScale=info`

````html ```` `colorScale=positive`

````html ```` `colorScale=negative`

````html ```` ### Custom Color Scale

```svelte ``` ### Legend #### Default

```html ``` #### With Filter

````svelte ```` ### Links

```html ``` ### State Abbreviations

```html ``` ## Options ### Data Query name, wrapped in curly braces Column to be used as the name for each state If true, map will look for two letter abbreviations rather than full names Column to be used as the value determining the colour of each state Colour scale to be used. To use a custom color palette, see the `colorPalette` prop Custom color palette to use for setting state colors. Overrides `colorScale`. E.g., `{['#cf0d06','#eb5752','#e88a87']}` Minimum value for the colour scale. Anything below the minimum will be shown in the same colour as the min value Maximum value for the colour scale. Anything above the maximum will be shown in the same colour as the max value Title appearing above the map. Is included when you click to save the map image Subtitle appearing just above the map. Is included when you click to save the map image Column containing links. When supplied, allows you to click each state on the map and navigate to the link Format to use for values ([see available formats](/core-concepts/formatting)) Whether to show a legend at the top of the map Whether to include filter controls on the legend. Can only be used when legend = true 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. 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.). Which chart renderer type (canvas or SVG) to use. See ECharts' [documentation on renderers](https://echarts.apache.org/handbook/en/best-practices/canvas-vs-svg/). ### Custom Echarts Options Custom Echarts options to override the default options. See [reference page](/components/echarts-options/) for available options. Custom Echarts options to override the default options for all series in the chart. This loops through the series to apply the settings rather than having to specify every series manually using `echartsOptions` See [reference page](/components/echarts-options/) for available options. Helper prop for custom chart development - inserts a code block with the current echarts config onto the page so you can see the options used and debug your custom options ### Interactivity Group name to connect this chart to other charts for synchronized tooltip hovering. Charts with the same `connectGroup` name will become connected --- evidence/sites/docs/pages/components/bubble-map/index.md --- --- title: Bubble Map sidebar_position: 1 ---

**Note:** you need to wrap the url in curly braces and backticks to avoid the curly braces in the URL being read as variables on your page ```svelte ### Custom Tooltip #### `tooltipType=hover`

```svelte ``` #### With clickable link and `tooltipType=click`

```svelte ``` ### Custom Color Palette

```svelte ``` ### Custom Styling

```svelte ``` ### Max Bubble Size

```svelte ``` ### Link Drilldown Pass in a `link` column to enable navigation on click of the point. These can be absolute or relative URLs

```svelte ``` ### Use Map as Input Use the `name` prop to set an input name for the map - when a point is clicked, it will set the input value to that row of data

```svelte ``` *Click a point on the map to see the input value get updated:* #### Selected value for `{inputs.my_point_map}`:

{JSON.stringify(inputs.my_point_map, null, 2)}

```svelte ``` #### Custom Colors Set custom legend colors using the `colorPalette` prop to match the number of categories; excess categorical options will default to standard colors.

```svelte ``` #### Scalar Legend

```svelte ``` #### Custom Colors Define scalar legend colors using the `colorPalette` prop, allowing specified colors to create a gradient based on the range of values.

```svelte ``` ## Options ### Bubbles Query result, referenced using curly braces Column containing latitude values Column containing longitude values Column that determines the size displayed for each point. Format string for displaying the size value in tooltips. Maximum size of the bubbles Column that determines the value displayed at each point (used for color scale) Format string for displaying the value. Column containing the names/labels of the points - by default, this is shown as the title of the tooltip. ### Color Scale Array of colors used for theming the points based on data Minimum value to use for the color scale. Maximum value to use for the color scale. ### Legend Appends a categorical or scalar legend to the map Determines the legend's position on the map, with options provided ### Interactivity URL to navigate to when a point is clicked. Input name. Can be referenced on your page with `{inputs.my_input_name}` ### Styling Color for the points. Use when you want all points to be the same color. Width of the border around each point. Color of the border around each point. Opacity of the points. ### Selected State When point is selected: Color for the points. Use when you want all points to be the same color. When point is selected: Width of the border around each point. When point is selected: Color of the border around each point. When point is selected: Opacity of the points. ### Tooltips Whether to show tooltips Determines whether tooltips are activated by hover or click. CSS class applied to the tooltip content. You can pass Tailwind classes into this prop to custom-style the tooltip Configuration for tooltips associated with each area. See below example for format #### `tooltip` example: ```javascript tooltip={[ {id: 'zip_code', fmt: 'id', showColumnName: false, valueClass: 'text-xl font-semibold'}, {id: 'sales', fmt: 'eur', fieldClass: 'text-[grey]', valueClass: 'text-[green]'}, {id: 'zip_code', showColumnName: false, contentType: 'link', linkLabel: 'Click here', valueClass: 'font-bold mt-1'} ]} ``` #### All options available in `tooltip`: - `id`: column ID - `title`: custom string to use as title of field - `fmt`: format to use for value - `showColumnName`: whether to show the column name. If `false`, only the value will be shown - `contentType`: currently can only be "link" - `linkLabel`: text to show for a link when contentType="link" - `formatColumnTitle`: whether to automatically uppercase the first letter of the title. Only applies when `title` not passed explicitly - `valueClass`: custom Tailwind classes to style the values - `fieldClass`: custom Tailwind classes to style the column names ### Base Map URL template for the basemap tiles. Attribution text to display on the map (e.g., "© OpenStreetMap contributors"). Optional title displayed above the map. Starting latitude for the map center. Starting longitude for the map center. Initial zoom level of the map. Height of the map in pixels. --- evidence/sites/docs/pages/components/print-format-components/index.md --- --- title: Print Format Components sidebar_position: 1 --- These components can be used to format your report content for PDF export or printing. ## LineBreak Inserts a line break on the page (in the UI as well as on print). This can be helpful when working with many input components (filters, dropdowns, etc.) ```html Text on original line Text on new line ``` ### Options Number of line breaks to insert ## PageBreak On print, inserts a page break - pushing the next content onto the start of a new page. ```html The purple line chart in this section will print on a new page. ``` ## PrintGroup - Combines content to be printed on the same page if possible - Offers a `hidden` prop. If `true`, the content within the PrintGroup will not be printed ```html The 2 heatmaps below will be printed on the same page if possible ``` ### `hidden=true` ```html The purple line chart will be hidden on print ``` ### Options If true, the content within the PrintGroup will not be printed --- evidence/sites/docs/pages/components/alert/index.md --- --- title: Alert sidebar_position: 1 ---

This is a default alert This is a informational alert This is a successful alert This is a warning alert This is a dangerous alert

```markdown This is a default alert This is a informational alert This is a successful alert This is a warning alert This is a dangerous alert ``` ## Options Changes the color of the alert --- evidence/sites/docs/pages/components/mixed-type-charts/index.md --- --- title: Mixed-Type Charts sidebar_position: 1 --- The easiest way to create mixed-type charts is setting up [a secondary y-axis in `LineChart`](/components/line-chart#secondary-axis-with-bar) or a [secondary axis in `BarChart`](/components/bar-chart#secondary-axis-with-line) You can combine multiple chart types inside a single `` tag to create mixed-type charts. ## Examples ### Mixed-Type Chart This example uses multiple y columns and multiple series types (bar and line)

```markdown ``` Because x is the first column in the dataset, an explicit `x` prop is not required. This structure also gives you control over the individual series on your chart. For example, if you have a single series running through a component, you can override props specifically for that series. Since the FDA acronym was not fully capitalized above, you can rename that specific series inside the `` primitive:

```markdown ``` # Chart `` ```markdown Insert primitives here ``` ## Data Query name, wrapped in curly braces Column to use for the x-axis of the chart Column(s) to use for the y-axis of the chart Whether to apply default sort to your data. Default is x ascending for number and date x-axes, and y descending for category x-axes Column to use as the series (groups) in a multi-series chart Format to use for x column ([see available formats](/core-concepts/formatting)) Format to use for y column ([see available formats](/core-concepts/formatting)) Whether to use a log scale for the y-axis Base to use when log scale is enabled 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. 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.). ## Chart Swap the x and y axes to create a horizontal chart Chart title. Appears at top left of chart. Chart subtitle. Appears just under title. Turns legend on or off. Legend appears at top center of chart. Minimum height of the chart area (excl. header and footer) in pixels. Adjusting the height affects all viewport sizes and may impact the mobile UX. Name to show under x-axis. If 'true', formatted column name is used. Only works with swapXY=false Name to show beside y-axis. If 'true', formatted column name is used. Turns on/off gridlines extending from x-axis tick marks (vertical lines when swapXY=false) Turns on/off gridlines extending from y-axis tick marks (horizontal lines when swapXY=false) Turns on/off value labels on the x-axis Turns on/off value labels on the y-axis Turns on/off thick axis line (line appears at y=0) Turns on/off thick axis line (line appears directly alongside the y-axis labels) Turns on/off tick marks for each of the x-axis labels Turns on/off tick marks for each of the y-axis labels Starting value for the y-axis Maximum value for the y-axis Whether to scale the y-axis to fit your data. yMin and yMax take precedence over yScale JavaScript object to add or override chart configuration settings (see Custom Charts page) Array of custom colours to use for the chart. E.g., `{['#cf0d06','#eb5752','#e88a87']}` Apply a specific color to each series in your chart. Unspecified series will receive colors from the built-in palette as normal. Note the double curly braces required in the syntax `seriesColors={{"Canada": "red", "US": "blue"}}` Which chart renderer type (canvas or SVG) to use. See ECharts' [documentation on renderers](https://echarts.apache.org/handbook/en/best-practices/canvas-vs-svg/). # Line `` ```markdown ``` ## Options Column(s) to use for the y-axis of the chart. Can be different than the y supplied to Chart Column to use as the series (groups) in a multi-series chart. Can be different than the series supplied to Chart Name to show in legend for a single series (to override column name) Color to override default series color. Only accepts a single color. % of the full color that should be rendered, with remainder being transparent Options to show breaks in a line (dashed or dotted) Thickness of line (in pixels) Turn on/off markers (shapes rendered onto the points of a line) Shape to use if markers=true Size of each shape (in pixels) Treatment of missing values in the dataset JavaScript object to add or override chart configuration settings (see Custom Charts page) # Area `` ```markdown ``` ## Options Column(s) to use for the y-axis of the chart. Can be different than the y supplied to Chart Column to use as the series (groups) in a multi-series chart. Can be different than the series supplied to Chart Name to show in legend for a single series (to override column name) Color to override default series color. Only accepts a single color. % of the full color that should be rendered, with remainder being transparent Show line on top of the area Treatment of missing values in the dataset JavaScript object to add or override chart configuration settings (see Custom Charts page) # Bar `` ```markdown ``` ## Options Column to use for the y-axis of the chart Name to show in legend for a single series (to override column name) Grouping method to use for multi-series charts Name for an individual stack. If separate Bar components are used with different stackNames, the chart will show multiple stacks Color to override default series color. Only accepts a single color. % of the full color that should be rendered, with remainder being transparent Width of line surrounding each bar Color to use for outline if outlineWidth > 0 JavaScript object to add or override chart configuration settings (see Custom Charts page) # Scatter `` ```markdown ``` ## Options Column to use for the y-axis of the chart Name to show in legend for a single series (to override column name) Options for which shape to use for scatter points Change size of all points on the chart % of the full color that should be rendered, with remainder being transparent Color to override default series color. Only accepts a single color. Width of line surrounding each shape Color to use for outline if outlineWidth > 0 JavaScript object to add or override chart configuration settings (see Custom Charts page) # Bubble `` ```markdown ``` ## Options Column to use for the y-axis of the chart Column to use to scale the size of the bubbles Name to show in legend for a single series (to override column name) Options for which shape to use for bubble points Minimum bubble size Maximum bubble size % of the full color that should be rendered, with remainder being transparent Color to override default series color. Only accepts a single color. Width of line surrounding each shape Color to use for outline if outlineWidth > 0 JavaScript object to add or override chart configuration settings (see Custom Charts page) # Hist `` ```markdown ``` ## Options Column which contains the data you want to summarize Color to override default series color % of the full color that should be rendered, with remainder being transparent JavaScript object to add or override chart configuration settings (see Custom Charts page) ### Interactivity Group name to connect this chart to other charts for synchronized tooltip hovering. Charts with the same `connectGroup` name will become connected ## Annotations Mixed type charts can include [annotations](/components/annotations) using the `ReferenceLine` and `ReferenceArea` components. These components are used within a chart component like so: ```html ``` --- evidence/sites/docs/pages/components/checkbox/index.md --- --- title: Checkbox sidebar_position: 1 --- Creates a checkbox with toggleable input. The Title and Name attributes can be defined, enabling the passing of true and false values.

````markdown ```` ### Checkbox using Default Value Defining the defaultValue property will set the initial checked value with true and false.

Selected Value: {inputs.name_of_checkbox}

```markdown Selected Value: {inputs.name_of_checkbox} ``` ```sql orders select COUNT(*) as records_count from needful_things.orders WHERE not ${inputs.exclude_low_value} -- When True, Do not evaluate the next condition OR ( ${inputs.exclude_low_value} -- Input is set to false AND sales < 10 -- Apply this condition ) ```

````markdown ```` # Checkbox ## Options Name of the checkbox, used to reference the selected value elsewhere as `{inputs.name.value}` Value to use when checkbox is first loaded. True value for checked, false for unchecked --- evidence/sites/docs/pages/components/annotations/index.md --- --- title: Annotations sidebar_position: 1 queries: - orders_by_month.sql - orders_by_category_2021.sql --- Annotations help you add important context directly within a chart - highlight important dates, time periods, or specific points on a chart to make it easier for your audience to pull insights from the information. ## At a glance Evidence currently offers 4 types of annotations, which can be defined inline or with a dataset: - [`ReferenceLine`](#reference-line): draw a line on a chart (e.g. sales target, launch dates, linear regression) - [`ReferenceArea`](#reference-area): highlight an area on a chart (e.g. holiday shopping periods, metric control ranges) - [`ReferencePoint`](#reference-point): highlight specific points on a chart (e.g. anomalies, points of interest) - [`Callout`](#callout): draw attention to data (e.g. data trend explanation)

Callout Data trending up here

```html Callout Data trending up here ``` # Reference Line Reference lines allow you to add lines to a chart to provide additional context within the visualization. These lines can be produced by providing a specific value (`y=50` or `x='2020-03-14'`) or by providing a dataset (e.g., `date`, `event_name`). If you provide coordinates for `[x, y]` and `[x2, y2]`, you can create sloped lines between points. When a dataset is provided, `ReferenceLine` can generate multiple lines - one for each row in the dataset. This can be helpful for plotting things like important milestones, launch dates, or experiment start dates. ## Examples ### Y-axis Defined Inline

```html ``` ### X-axis Defined Inline

```html ``` ### Y-axis Multiple Lines

```html ``` ### X-axis from Data ```sql multiple_dates select '2019-12-05'::date as start_date, '2020-02-05'::date as end_date, 'Campaign 1' as campaign_name union all select '2020-07-14'::date, '2020-09-14'::date, 'Campaign 2' union all select '2021-04-14'::date, '2021-06-14'::date, 'Campaign 3' ```

```html ``` ### Sloped Line Inline

```html ``` ### Linear Regression from Data ```sql orders_by_state select state, sum(sales) as sales, count(*) as num_orders from orders group by all ``` ```sql regression WITH coeffs AS ( SELECT regr_slope(num_orders, sales) AS slope, regr_intercept(num_orders, sales) AS intercept, regr_r2(num_orders, sales) AS r_squared FROM ${orders_by_state} ) SELECT min(sales) AS x, max(sales) AS x2, min(sales) * slope + intercept AS y, max(sales) * slope + intercept AS y2, 'Best Fit (y = ' || ROUND(slope, 2) || 'x + ' || ROUND(intercept, 2) || ', R^2 = ' || ROUND(r_squared, 3) || ')' AS label FROM coeffs, ${orders_by_state} GROUP BY slope, intercept, r_squared ```

```html ``` ````markdown ```sql orders_by_state select state, sum(sales) as sales, count(*) as num_orders from orders group by all ``` ```sql regression WITH coeffs AS ( SELECT regr_slope(num_orders, sales) AS slope, regr_intercept(num_orders, sales) AS intercept, regr_r2(num_orders, sales) AS r_squared FROM ${orders_by_state} ) SELECT min(sales) AS x, max(sales) AS x2, min(sales) * slope + intercept AS y, max(sales) * slope + intercept AS y2, 'Best Fit (y = ' || ROUND(slope, 2) || 'x + ' || ROUND(intercept, 2) || ', R^2 = ' || ROUND(r_squared, 3) || ')' AS label FROM coeffs, ${orders_by_state} GROUP BY slope, intercept, r_squared ``` ```` ### Custom Styling

```html ``` ### Label Positions

```html ``` ### Colours

```html ``` ## Options A reference line can be produced by defining values inline or by supplying a dataset, and the required props are different for each of those cases. ### Defining Values Inline This table shows how you combine `x`, `y`, `x2`, and `y2` to create different types of lines: ```sql xy_config_table select 5 as x, null as y, null as x2, null as y2, 'Vertical line at x=5' as Result union all select null, 100, null, null, 'Horizontal line at y=100' union all select 5, 100, null, null, 'Vertical line at x=5 (ignores y)' union all select 5, 100, 10, 200, 'Sloped line from [5, 100] to [10, 200]' union all select 5, 100, null, 200, 'Vertical line from [5, 100] to [5, 200]' union all select 5, 100, 10, null, 'Horizontal line from [5, 100] to [10, 100]' order by 2 nulls first, 1 nulls first, 3 nulls first, 4 nulls first ``` If you provide `[x, y]` and `[x2, y2]`, coordinates must fall within the chart's boundaries in order for the line to be drawn. ### Supplying a Dataset ```sql xy_data_table select 'x_col' as x, null as y, null as x2, null as y2, 'Vertical lines at values in x_col' as Result union all select null, 'y_col', null, null, 'Horizontal lines at values in y_col' union all select 'x_col', 'y_col', null, null, 'Vertical lines at x_col (ignores y_col)' union all select 'x_col', 'y_col', 'x2_col', 'y2_col', 'Sloped Lines from [x_col, y_col] to [x2_col, y2_col]' order by 2 nulls first, 1 nulls first, 3 nulls first, 4 nulls first ``` If you provide `[x, y]` and `[x2, y2]`, coordinates must fall within the chart's boundaries in order for lines to be drawn. ### Styling