UI & Theming

Blocklets are not just backend services; they are often user-facing applications that need to integrate seamlessly into a larger user interface. The navigation and theme properties in blocklet.yml provide a declarative way for a blocklet to contribute its UI elements and styling preferences to the host environment, enabling a cohesive and composable user experience.

Navigation#

The navigation property defines a list of menu items that the blocklet exposes. The host application (e.g., a Blocklet Server dashboard) reads this metadata from all installed blocklets and dynamically constructs the application's menus, sidebars, and other navigational structures. This allows for powerful UI composition where different blocklets contribute to a unified interface.

The property is an array of navigationItem objects, each representing a link, a submenu, or a link to a child component.

navigationItem Properties#

Property	Type	Description
id	string	A unique identifier for the navigation item, scoped to its parent. It must follow JavaScript variable naming rules. This ID is used for merging and overriding user settings.
title	string | object	The text displayed for the menu item. Can be a simple string or an object for internationalization (i18n), e.g., { "en": "Home", "zh": "首页" }. Required.
description	string | object	A short description of the navigation item, often used as a tooltip. Also supports i18n.
link	string | object	The URL path for the navigation item. If it starts with /, it's relative to the blocklet's mount point. Absolute URLs are also supported. Also supports i18n.
component	string	The name or DID of a child blocklet defined in the components section. This links the navigation item to another blocklet, automatically inheriting its navigation or linking to its mount point. child is an alias for this property.
section	string | string[]	Specifies where the navigation item should appear in the UI. A single item can be placed in multiple sections. Common values include header, footer, userCenter, dashboard, social, and bottomNavigation.
role	string | string[]	A list of user roles required to see and access this navigation item, enabling basic access control.
icon	string	An identifier for an icon to be displayed next to the title. The icon library is dependent on the host environment.
visible	boolean	Controls the default visibility of the item. Defaults to true.
private	boolean	If true, this item will only be visible to the owner of the user center/profile page. Useful for settings or admin links.
items	navigationItem[]	An array of navigationItem objects to create a nested submenu.

Navigation Composition#

When a navigation item uses the component property, the system dynamically integrates the child blocklet's UI. This process is a cornerstone of blocklet composability.

In this diagram, the Root Blocklet doesn't need to know the internal routes of the blog-component. It simply declares its intent to include the component in the navigation. The system handles the rest, including prefixing the child's links with its assigned mount point (e.g., /blog).

Examples#

1. Basic Link

This creates a simple link to /about-us within the blocklet.

2. Nested Submenu with i18n

This example defines a "Services" dropdown menu with internationalized titles.

3. Component Integration

Here, a top-level blocklet integrates a billing-portal component into its settings area.

Theme#

The theme property allows a blocklet to suggest basic styling, such as background colors or images, to the host environment. This helps maintain a consistent look and feel, especially when the blocklet is used as a primary interface.

The host application has the final say on whether to apply the suggested theme.

theme Properties#

Property	Type	Description
background	string | object	Defines the background style. It can be a single CSS background value (e.g., #FFFFFF or url(...)) applied globally, or an object to specify backgrounds for different UI regions.
background.header	string	The CSS background for the header region.
background.footer	string	The CSS background for the footer region.
background.default	string	The CSS background for the main content area or as a fallback.

Examples#

1. Simple Color Background

2. Region-Specific Backgrounds

This sets a gradient for the header and a solid color for the rest of the page.

By defining navigation and theme, you ensure your blocklet is a good citizen in a larger ecosystem. Next, let's explore how to configure monetization for your blocklet in the Monetization section.