Widgets

STAC Browser has a pluggable widget system that lets you inject custom Vue components into specific locations on the page. Widgets can display pretty much any content you need - using either the pre-defined widgets or your own Vue components.

• User Guide
  • Configuration File
  • Using Pre-defined Widgets
  • Using Custom Components
  • Conditional Widgets
• Pre-defined Widgets
  • AlertBox
  • CustomText
  • Featured
• Hooks
  • StacBrowser.vue
  • views/ApiSearch.vue
  • views/Catalog.vue
  • views/Item.vue
  • views/SelectDataSource.vue
• Developer Guide
  • Creating a New Widget
  • Adding a New Hook

User Guide

Configuration File

Widgets are configured in widgets.config.js at the project root. The file exports an object where each key is a hook ID (the location on the page, see below) and each value is an array of widget definitions to render at that location.

Multiple widgets can be added to the same hook — they render in array order.

After editing the file, restart or rebuild STAC Browser for changes to take effect.

Using Pre-defined Widgets

For pre-defined widgets (located in src/widgets), specify the id (filename without the .vue extension) and any props:

{
  id: 'AlertBox',
  props: {
    title: 'Warning',
    text: 'This catalog is currently under maintenance.'
  }
}

Using Custom Components

To use a component from outside src/widgets/, import it with Vue's defineAsyncComponent and assign it to the component property:

{
  id: 'MyCustomWidget',
  component: defineAsyncComponent(() => import('../MyCustomWidget.vue')),
  props: {
    myOption: true
  }
}

Make sure the beginning of the config file includes:

import { defineAsyncComponent } from 'vue';

Conditional Widgets

By default, a widget renders whenever its hook renders. To limit a widget to specific situations, add a condition function to the widget definition. The widget is only shown when the function returns true. It receives an object with the currently shown STAC entity (data) and the Vuex store state and getters.

For example, to show a widget only on the landing page:

{
  id: 'AlertBox',
  condition: ({ data, getters }) => Boolean(data && getters.root && data.is(getters.root)),
  props: {
    text: 'Welcome!'
  }
}

Or only for collections:

condition: ({ data }) => Boolean(data?.isCollection)

Pre-defined Widgets

All pre-defined widgets are stored in src/widgets.

AlertBox

Renders a dismissible alert banner.

Props	Type	Default	Description
title	String	''	Bold heading shown before the text.
text	String	''	The alert message body, CommonMark (Markdown) is supported.
variant	String	'warning'	Color variant: 'warning', 'danger', 'success', 'info', etc.
dismissible	Boolean	false	Whether the user can close the alert.
allowHTML	Boolean	false	Allows HTML tags in the text.

CustomText

Renders a simple text with a heading.

Props	Type	Default	Description
title	String	''	Rendered as an <h3> heading.
text	String	''	Rendered as the body, CommonMark (Markdown) is supported.
allowHTML	Boolean	false	Allows HTML tags in the text.

Featured

Renders a list of "featured" STAC catalogs or collections. A typical placement is the view-catalog-catalogs-start hook, which shows the featured entities right above the regular collection list. The widget only renders on the landing page (the root catalog).

Props	Type	Default	Description
entities	Array	required	The entities to feature, shown in the given order. See below for the supported types of entries.
title	String	null	Rendered as the heading of the list. Can be given as plain text or as the key of a phrase from the locales (e.g. defined in the custom.json files, see the localization docs). If not given, defaults to a localized version of "Featured".
view	String	'cards'	How the entities are shown: 'cards' or 'list'. Set to null to follow the view mode that the user has chosen for the other lists.

Each entry in entities can be one of the following:

• A collection ID (a string without a slash, e.g. 'sentinel-2-l2a'): Only works for STAC APIs.
• A URL (a string with a slash, absolute or relative to the catalog, e.g. 'https://example.com/api/collections/xyz' or './data/catalog.json'): Works for both STAC APIs and static catalogs. Entities that fail to load are not shown.
• A (partially) complete STAC entity as object (e.g. { id: 'xyz', title: 'My Collection', description: '…', links: […] }): Works for both STAC APIs and static catalogs. The object must contain a self link or (for APIs) an id, otherwise the entity is not shown. STAC Browser loads the full version of the entity when needed.

Hooks

Hooks are named insertion points in the STAC Browser UI where widgets get rendered. Each hook has an ID like view-catalog-meta-start that you use as the key in widgets.config.js.

StacBrowser.vue

• footer-start
• root-before-content
• root-end
• root-start

views/ApiSearch.vue

• view-search-filters-collections-end
• view-search-filters-collections-start
• view-search-filters-end
• view-search-filters-items-end
• view-search-filters-items-start
• view-search-filters-start
• view-search-results-end
• view-search-results-start

views/Catalog.vue

• view-catalog-catalogs-end
• view-catalog-catalogs-start
• view-catalog-items-end
• view-catalog-items-start
• view-catalog-meta-end
• view-catalog-meta-start

views/Item.vue

• view-item-primary-end
• view-item-primary-start
• view-item-secondary-end
• view-item-secondary-start

views/SelectDataSource.vue

• view-select-data-source-start

Note: This list is auto-generated. Run npm run docs:hooks to update it after adding new hooks.

Developer Guide

Creating a New Widget

A widget is a standard Vue single-file component (.vue file). To create one:

1. Create the component file in src/widgets/ or at another location of your choice. The filename (without extension) must match the component's name property exactly (case-sensitive).

   For example, src/widgets/BannerImage.vue:

   <template>
     <div class="banner-image">
       <img :src="url" :alt="alt" />
     </div>
   </template>
   
   <script>
   export default {
     name: "BannerImage",
     props: {
       url: {
         type: String,
         required: true
       },
       alt: {
         type: String,
         default: ''
       }
     }
   };
   </script>
   
   <style lang="scss" scoped>
   @import "../theme/variables.scss";
   
   .banner-image {
     margin-bottom: $block-gap;
   
     img {
       max-width: 100%;
     }
   }
   </style>
   

2. Register it in widgets.config.js under the desired hook:

   export default {
     'view-catalog-meta-start': [
       {
         id: 'BannerImage',
         props: {
           url: '/banner.jpg',
           alt: 'Catalog banner'
         }
       },
     ],
   };
   

3. Rebuild STAC Browser. The widget will be dynamically imported when the hook renders.

Tips:

• Use @import "../theme/variables.scss" to access shared SCSS variables like $block-gap.
• Widgets only receive the props defined in widgets.config.js — they do not automatically receive page data such as the STAC object or items. You can import them from the Vuex store.
• You can place the same widget at multiple hooks with different props.

Adding a New Hook

To add a new widget insertion point to a view:

1. Add a <WidgetHook> tag in the Vue template of the relevant view or component:

   <WidgetHook id="view-catalog-custom-start" />
   

   WidgetHook is registered as a global component, so no import is needed.

2. Update the docs by running:

   npm run docs:hooks
   

   This scans all .vue files for <WidgetHook> tags and updates the hook list in this document automatically.