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.
- Unsupported UI or custom mini-widget: host a separate page/app and embed it with the iFrame widget. Read iframe-widgets.md.
- Supported third-party data: configure a Homarr integration and matching native widget. Read 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.
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
- Identify whether the task is CSS, iframe, app, integration, or native widget work.
- Prefer official Homarr settings and built-in integrations before custom code.
- For CSS, use widget custom classes and board-scoped CSS; avoid generated Mantine suffix classes.
- For iframes, verify client-reachable URL, protocol, frame headers, theme, and transparent body.
- For integrations, verify base URL, secrets, server/container reachability, and test connection.
- For native widgets, verify supported integrations, options, loading/empty/error states, edit/preview mode, and permissions.
- Make minimal reversible changes.
- Verify with curl/headers/DevTools and, for Homarr source work, lint/typecheck/test.
- 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.