Filters

Overview

Filters allow users to refine the displayed data using the sidebar. They are configured in the settings.filters array.

import type { Config } from "@envisioning/app";

const settings: Config["settings"] = {
  filters: [
    {
      type: "SELECTION",
      label: { en: "Category" },
      joinKey: "collection",
    },
    {
      type: "RANGE",
      label: { en: "Metrics" },
      sliders: [
        { joinKey: "trl" },
        { joinKey: "cost" },
      ],
    },
  ],
  // ...
};

Filter Types

Selection Filter

Checkbox/radio selection from tag or cluster values:

{
  type: "SELECTION",
  label: { en: "Collection" },
  joinKey: "collection",
}

Property	Type	Required	Description
`type`	`"SELECTION"`	Yes	Filter type
`label`	`I18n`	Yes	Display label
`joinKey`	`string`	Yes	Schema join key

Range Filter

Slider for numeric metric ranges:

{
  type: "RANGE",
  label: { en: "Metrics" },
  sliders: [
    {
      joinKey: "trl",
      resultLabel: "{block.currentValue} - {block.label}",
    },
    {
      joinKey: "cost",
      resultLabel: "{block.currentValue} - {block.label}",
    },
  ],
}

Property	Type	Required	Description
`type`	`"RANGE"`	Yes	Filter type
`label`	`I18n`	Yes	Section label
`sliders`	`array`	Yes	Slider configurations

Range Slider Properties

Property	Type	Required	Description
`joinKey`	`string`	Yes	Schema join key for the metric
`resultLabel`	`string`	No	Template for selected value display
`helpSettings`	`object`	No	Help tooltip configuration

Result Label Templates

{
  joinKey: "trl",
  resultLabel: "{block.currentValue} - {block.label}",
}

Available template variables:

{block.currentValue} - Currently selected value
{block.label} - Metric label from schema
{block.min} - Minimum value
{block.max} - Maximum value

Selection Filter Examples

Filter by Cluster

{
  type: "SELECTION",
  label: { en: "Collection" },
  joinKey: "collection",
}

Users can select one or more collections to filter entities.

Filter by Tag

{
  type: "SELECTION",
  label: { en: "Categories" },
  joinKey: "category",
}

Users can select tags to show only matching entities.

Range Filter Examples

Single Metric Range

{
  type: "RANGE",
  label: { en: "TRL Range" },
  sliders: [
    {
      joinKey: "trl",
      resultLabel: "TRL {block.currentValue}",
    },
  ],
}

Multiple Metrics

{
  type: "RANGE",
  label: { en: "Metrics" },
  sliders: [
    {
      joinKey: "trl",
      resultLabel: "{block.currentValue} - {block.label}",
    },
    {
      joinKey: "cost",
      resultLabel: "{block.currentValue} - {block.label}",
    },
    {
      joinKey: "skills",
      resultLabel: "{block.currentValue} - {block.label}",
    },
    {
      joinKey: "socialAcceptance",
      resultLabel: "{block.currentValue} - {block.label}",
    },
  ],
}

Help Settings

Add help tooltips to range sliders:

{
  joinKey: "trl",
  resultLabel: "{block.currentValue}",
  helpSettings: {
    title: { en: "Technology Readiness Level" },
    description: { en: "Measures the maturity of a technology." },
    link: "https://example.com/trl-explained",
  },
}

Complete Example

import type { Config } from "@envisioning/app";

export const settings: Config["settings"] = {
  // ...other settings

  filters: [
    // Range filter with multiple metrics
    {
      type: "RANGE",
      label: { en: "Metrics" },
      sliders: [
        {
          joinKey: "trl",
          resultLabel: "{block.currentValue} - {block.label}",
        },
        {
          joinKey: "cost",
          resultLabel: "{block.currentValue} - {block.label}",
        },
        {
          joinKey: "skills",
          resultLabel: "{block.currentValue} - {block.label}",
        },
        {
          joinKey: "socialAcceptance",
          resultLabel: "{block.currentValue} - {block.label}",
        },
        {
          joinKey: "policyAndRegulation",
          resultLabel: "{block.currentValue} - {block.label}",
        },
        {
          joinKey: "ndcImpact",
          resultLabel: "{block.currentValue} - {block.label}",
        },
        {
          joinKey: "energyCost",
          resultLabel: "{block.currentValue} - {block.label}",
        },
        {
          joinKey: "fundingOpportunities",
          resultLabel: "{block.currentValue} - {block.label}",
        },
      ],
    },

    // Selection filter for clusters
    {
      type: "SELECTION",
      label: { en: "Collection" },
      joinKey: "collection",
    },
  ],
};

How Filters Work

Selection Filters - Show checkboxes for each value in the schema object. Selecting values shows only entities that match.
Range Filters - Show sliders for metric ranges. Moving sliders filters entities to those within the selected range.
Filter Combination - Multiple filters are combined with AND logic. Entities must match all active filters to be displayed.

Schema Requirements

Filters require corresponding schema definitions:

// Schema for selection filter
collection: {
  type: "cluster",
  src: "allCollections",
  // ...
}

// Schema for range filter
trl: {
  type: "metric",
  src: "self",
  metricDomain: [1, 9],
  // ...
}

The joinKey in filters must match:

A schema object key for selection filters
A metric schema key for range filters
An entity join key that connects to the filter target

Filters

On this page