Work on Homarr dashboards, board styling, custom CSS, iframe widgets, embedded mini-apps, native widgets, apps, and integrations. Use when requests mention H...
--- name: homarr description: Work on Homarr dashboards, board styling, custom CSS, iframe widgets, embedded mini-apps, native widgets, apps, and integrations. Use when requests mention Homarr, Homarr widgets, iframe embeds, dashboard items, board appearance, Mantine/custom CSS in Homarr, Homarr integrations, or contributing/fixing Homarr native widgets/integrations. --- # Homarr Use this skill to choose the right Homarr path, avoid fragile CSS, and verify iframe/widget/integration work. ## Start with the right category Classify the request first: - **Board visual tweak**: use Homarr board appearance settings first; use scoped custom CSS only when needed. Read [styling.md](references/styling.md). - **Unsupported UI or custom mini-widget**: host a separate page/app and embed it with the iFrame widget. Read [iframe-widgets.md](references/iframe-widgets.md). - **Supported third-party data**: configure a Homarr integration and matching native widget. Read [native-widgets-integrations.md](references/native-widgets-integrations.md). - **Unsupported service but native Homarr behavior is required**: modify/contribute Homarr source; keep secrets server-side. Read [native-widgets-integrations.md](references/native-widgets-integrations.md). Do not promise runtime custom widgets/plugins: official Homarr does not support arbitrary custom widgets as runtime extensions. Practical alternatives are built-in widgets, iFrame embeds, custom CSS, or source contributions. ## Core concepts Keep these distinct: - **Board**: dashboard page containing items. - **App**: link/bookmark entry with URL, icon, description, optional ping URL. - **Integration**: Homarr server-side connection to a supported third-party service. - **Widget**: board item that shows data or controls an integration. - **iFrame widget**: browser embed of an external URL; Homarr does not proxy traffic. ## General workflow 1. Identify whether the task is CSS, iframe, app, integration, or native widget work. 2. Prefer official Homarr settings and built-in integrations before custom code. 3. For CSS, use widget custom classes and board-scoped CSS; avoid generated Mantine suffix classes. 4. For iframes, verify client-reachable URL, protocol, frame headers, theme, and transparent body. 5. For integrations, verify base URL, secrets, server/container reachability, and test connection. 6. For native widgets, verify supported integrations, options, loading/empty/error states, edit/preview mode, and permissions. 7. Make minimal reversible changes. 8. Verify with curl/headers/DevTools and, for Homarr source work, lint/typecheck/test. 9. Document any fragile selectors, unsupported CSS assumptions, or reverse-proxy/header requirements. ## Quick decisions | Need | Use | |---|---| | Change board/item colors/radius/background | Board appearance first, then scoped custom CSS | | Style one widget | Widget custom class + board custom CSS | | Embed unsupported web UI | iFrame widget | | Embed custom mini-widget | Separate HTML/app + iFrame widget | | Show data from supported service | Integration + supported native widget | | Show unsupported service natively | Homarr source contribution | | Hide unauthorized control | Permissions, not CSS | | Fix white iframe background | `theme=dark`, transparent body, inner container, headers/mixed-content checks | | Fix “card inside card” | Remove inner wrapper background/border/radius/shadow/blur | ## Official docs to check - Styling: `https://homarr.dev/docs/advanced/styling/` - Boards: `https://homarr.dev/docs/management/boards/` - iFrame widget: `https://homarr.dev/docs/widgets/iframe/` - Apps: `https://homarr.dev/docs/management/apps/` - Integrations: `https://homarr.dev/docs/management/integrations/` - Widgets catalog: `https://homarr.dev/docs/category/widgets/` - Integrations catalog: `https://homarr.dev/docs/category/integrations/` - FAQ/custom widgets: `https://homarr.dev/docs/community/faq/` - Developer setup: `https://homarr.dev/docs/advanced/development/getting-started/` - Third-party iframe reference: `https://github.com/diogovalentte/homarr-iframes` ## Safety rules - Treat custom CSS as unsupported and potentially fragile after updates. - Do not use CSS as security or permissions. - Do not expose API keys in CSS, iframe URLs, or client-rendered code. - For native integrations, keep secrets server-side through Homarr integration APIs. - For iframes, enable only needed permissions such as fullscreen, autoplay, microphone, camera, geolocation, payment, or modals. - Remember public boards may expose visible embedded content to unauthenticated users if board access allows it.
don't have the plugin yet? install it then click "run inline in claude" again.