82 lines
4.8 KiB
Plaintext
82 lines
4.8 KiB
Plaintext
---
|
|
title: Custom Widgets
|
|
sidebar_label: Overview
|
|
tags: [Custom Widgets, API, JSX, MCP]
|
|
---
|
|
|
|
import { BundledCustomWidgetGallery, CustomWidgetCodeExample } from "@site/src/components/custom-widget-code";
|
|
|
|
export const completeManifest = `{
|
|
"$schema": "homarr-custom-widget-v2",
|
|
"name": "Service status",
|
|
"sources": {
|
|
"default": { "name": "Service API", "baseUrl": "https://status.example.com", "networkScope": "public", "auth": "none" }
|
|
},
|
|
"requests": { "status": { "path": "/api/status" } },
|
|
"options": {},
|
|
"template": "<Badge color={data.status?.ok ? 'green' : 'red'}>{data.status?.label ?? 'Unknown'}</Badge>"
|
|
}`;
|
|
|
|
# Custom Widgets
|
|
|
|
:::warning Experimental feature
|
|
|
|
This feature is experimental and will probably change. If you encounter bugs, need more capabilities, or find something confusing, tell us in the [official discussion thread](https://github.com/homarr-labs/homarr/discussions/categories/custom-widgets). Your feedback directly shapes what comes next. Happy hacking!
|
|
|
|
:::
|
|
|
|
Custom JSX v2 is Homarr's only Custom Widget format. A definition contains keyed API sources, keyed requests, optional widget options, and one safe JSX template. Credentials are encrypted separately and never exported.
|
|
|
|
```ts
|
|
interface HomarrCustomWidgetV2 {
|
|
$schema: "homarr-custom-widget-v2";
|
|
name: string;
|
|
description?: string;
|
|
iconUrl?: string;
|
|
sources: Record<string, CustomWidgetSource>;
|
|
requests: Record<string, CustomWidgetRequest>;
|
|
options?: Record<string, CustomWidgetOption>;
|
|
template: string;
|
|
}
|
|
```
|
|
|
|
<CustomWidgetCodeExample
|
|
id="complete-widget-manifest"
|
|
label="Complete manifest"
|
|
code={completeManifest}
|
|
height="360px"
|
|
/>
|
|
|
|
The browser renders JSX. Homarr's server executes named requests, applies board permissions and network protections, and injects credentials. The browser never receives source credentials.
|
|
|
|
## Authoring paths
|
|
|
|
- [Create a Custom Widget](./authoring) visually or with one copied AI prompt.
|
|
- [Use the JSX runtime](./custom-jsx) for data, Mantine components, temporary inputs, and diagnostics.
|
|
- [Browse the supported component reference](./component-reference).
|
|
- [Configure requests and security](./requests-and-security).
|
|
- [Use MCP and the skills.sh skill](./agent-authoring).
|
|
- [Correct problems](./troubleshooting).
|
|
|
|
The workbench keeps one continuous layout with visual source, request, and option editors. Advanced raw JSON remains available for experts and AI paste. Invalid values stay inline and disable both preview and Save/Create until they are corrected.
|
|
|
|
Exports, imports, Workshop, MCP, and storage all validate the same schema. Widgets saved in the legacy format remain visible with a **Migration required** badge after upgrading. Use **Copy migration prompt**, give the redacted prompt to an LLM, then import its v2 JSON from that widget's action menu. Homarr keeps the legacy record until the replacement validates and is confirmed; credentials are never included in the prompt.
|
|
|
|
When adding widgets while editing a board, the Custom Widgets section always includes **Install from Workshop**. The Workshop and API source review open above the widget picker without closing it. After import, the new definition appears in the picker. Its tile waits for the board to be saved before server requests run and loads automatically after a successful save; no page reload is required.
|
|
|
|
## Import and Workshop
|
|
|
|
Import review shows origins, authentication modes, network scopes, methods, actions, and permissions. Every source has a suggested URL, but private and loopback sources must be confirmed or replaced for the current Homarr installation. The same screen accepts API keys, tokens, usernames, and passwords; credentials remain optional at install time and missing values stay visible on the Custom Widgets page.
|
|
|
|
For example, installing **Tautulli Activity** asks for both the user's Tautulli URL and API key. A stable public source such as PokéAPI keeps its published URL without creating unnecessary setup work.
|
|
|
|
Workshop publishes technically valid widgets immediately; users can vote or report them, and administrators can delete submissions. Publishers should replace personal private-network hosts with a clear service placeholder before publishing.
|
|
|
|
Connected agents can search, inspect, and install Workshop widgets with `customWidget_workshopSearch`, `customWidget_workshopGet`, and `customWidget_workshopInstall`. After installation they can set a source URL and credentials with `customWidget_sourceConfigure`, or create a secure user-facing setup URL with `customWidget_configurationRequestUser`. Secret values are never returned through MCP.
|
|
|
|
## Bundled examples
|
|
|
|
Homarr seeds five disabled examples without credentials and never overwrites an edited seed. They use the same public contract. The Tautulli example is the highest-scoring widget preserved from Homarr's AI authoring evaluation:
|
|
|
|
<BundledCustomWidgetGallery />
|