73 lines
3.2 KiB
Plaintext
73 lines
3.2 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.
|
|
- [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 only disable the widget preview.
|
|
|
|
Exports, imports, Workshop, MCP, and storage all validate the same schema. Old formats are rejected. A missing definition only renders **Custom widget unavailable** inside its tile.
|
|
|
|
## Import and Workshop
|
|
|
|
Import review shows origins, authentication modes, network scopes, methods, actions, and permissions. It also lets the user supply each required credential before import. Workshop publishes technically valid widgets immediately; users can vote or report them, and administrators can delete submissions.
|
|
|
|
## 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 />
|