Navigation links for filtering a dataset by a category, status, owner, or other attribute.
This component only renders the filter navigation. Your SQL query is responsible for filtering the data based on the URL parameter selected by the user.
Use it alongside a table, list, or card. The links use GET parameters, so the selected filter can be bookmarked and shared.
Set compact to display the facets in a dropdown, which is useful for a moderate number of choices or on narrow screens. Use selected_facet to show the active facet in the closed dropdown. all_link and all_title add a link that clears the filter.
The following portable pattern filters a table by category. sqlpage.link preserves the current page path while safely generating the URL.
select 'table' as component;
select title, category
from my_table
where $category is null or category = $category;
select 'facet' as component,
'Category' as description,
sqlpage.link(sqlpage.path(), json_object('category', null)) as all_link,
$category is null as all_active;
select distinct category as title,
sqlpage.link(sqlpage.path(), json_object('category', category)) as link,
category = $category as active
from my_table
order by category;
Introduced in SQLPage v0.46.0.
Top-level parameters
name
required
type
description
all_active
BOOLEAN
Whether the link that clears the filter is active. Defaults to false.
all_link
URL
URL that clears the filter. If omitted, no All link is displayed.
all_title
TEXT
Text for the link that clears the filter. Defaults to "ALL".
center
BOOLEAN
Whether to center the facet selector
class
TEXT
class attribute added to the container in HTML. It can be used to apply custom styling to this item through css. Added in v0.18.0.
compact
BOOLEAN
Displays the facets in a dropdown instead of links.
description
TEXT
The facet category label.
dropdown_title
TEXT
Text shown on the compact-mode dropdown button when no facet is selected. Defaults to Choose facet.
id
TEXT
id attribute added to the container in HTML. It can be used to target this item through css or for scrolling to this item through links (use "#id" in link url).
selected_facet
TEXT
An alias for dropdown_title.
Row-level parameters
name
required
type
description
link
REQUIRED
URL
URL for the facet.
title
REQUIRED
TEXT
Facet title.
active
BOOLEAN
Whether the link is active or not. Defaults to false.
Example 1
A category selector with an All link. In an application, the SQL pattern above uses the chosen URL parameter to filter the displayed data.
select
'table' as component;
select
'USS Enterprise (NCC-1701)' as name,
'Constitution' as class;
select
'USS Exeter (NCC-1672)' as name,
'Galaxy' as class;
select
'USS Exeter (NCC-1672)' as name,
'Constitution' as class;
select
'facet' as component,
'Classes' as description,
'?component=facet' as all_link,
'All' as all_title,
FALSE as all_active;
select
'Constitution' as title,
'?component=facet&class=Constitution' as link,
TRUE as active;
select
'Galaxy' as title,
'?component=facet&class=Galaxy' as link;
Result
name
class
USS Enterprise (NCC-1701)
Constitution
USS Exeter (NCC-1672)
Galaxy
USS Exeter (NCC-1672)
Constitution
Example 2
Compact mode displays the facet choices in a dropdown.
select
'table' as component;
select
'USS Enterprise (NCC-1701)' as name,
'Constitution' as class;
select
'USS Defiant (NCC-1764)' as name,
'Constitution' as class;
select
'USS Exeter (NCC-1672)' as name,
'Constitution' as class;
select
'facet' as component,
'Classes' as description,
'?component=facet' as all_link,
'All' as all_title,
FALSE as all_active,
TRUE as compact,
'Select a spaceship class' as dropdown_title,
'Constitution' as selected_facet;
select
'Constitution' as title,
'?component=facet&class=Constitution' as link,
TRUE as active;
select
'Galaxy' as title,
'?component=facet&class=Galaxy' as link;