Skip to main content
Widgets are the building blocks of your Homarr dashboard. This guide will walk you through adding widgets to your boards, configuring their settings, and customizing their appearance.

​
Adding Widgets to Your Board

1

Enter Edit Mode

Click the Edit button in the top-right corner of your board to enable edit mode. This allows you to add and modify widgets.
2

Add a New Widget

Click the Add Widget button (usually represented by a plus icon). A widget selection modal will appear showing all available widget types.
3

Select Widget Type

Choose from the available widget categories:
  • Media: Media server, media requests, media releases
  • Downloads: Download clients, indexer manager
  • System: System resources, health monitoring, Docker containers
  • Smart Home: Entity state, execute automation
  • Utilities: Clock, calendar, weather, notebook, RSS feed
  • Integrations: Integration-specific widgets
Click on the widget type you want to add.
4

Configure Initial Settings

After selecting a widget type, you’ll be prompted to configure its basic settings:
  • Integration: Select which integration(s) this widget should connect to (if applicable)
  • Widget Options: Configure widget-specific settings like refresh intervals, display modes, etc.
Click Save to add the widget to your board.
Some widgets require integrations to function. Make sure you’ve set up the necessary integrations before adding these widgets. See the Integrations Overview for more details.

​
Widget Positioning and Sizing

​
Moving Widgets

In edit mode, widgets can be repositioned by dragging them:
  1. Click and hold the widget’s header
  2. Drag it to the desired location
  3. Release to drop it in place
The grid system will automatically adjust other widgets to accommodate the move.

​
Resizing Widgets

To resize a widget:
  1. Enter edit mode
  2. Hover over the widget’s edges or corners until you see the resize handle
  3. Click and drag to resize
  4. Release when you’ve reached the desired size
Each widget has minimum and maximum size constraints based on its content requirements. The system will prevent you from making a widget too small to display its content properly.

​
Grid Layout

Homarr uses a responsive grid layout system:
  • Desktop: 12 columns wide
  • Tablet: 8 columns wide
  • Mobile: 4 columns wide
Widgets automatically adapt their layout based on screen size.

​
Configuring Widget Settings

​
Accessing Widget Settings

1

Open Edit Mode

Enter edit mode by clicking the Edit button.
2

Open Widget Settings

Click the Settings icon (gear icon) on the widget you want to configure.
3

Configure Options

The widget settings modal will appear with various configuration options depending on the widget type.

​
Common Widget Options

Most widgets share these common configuration options:
Select which integration(s) the widget should use to fetch data. Some widgets support multiple integrations simultaneously.Example: The media server widget can connect to multiple Plex, Jellyfin, or Emby servers.
Control how often the widget updates its data. Options typically range from 10 seconds to several minutes.
Setting very short refresh intervals may impact performance and increase API calls to your services.
Customize how the widget displays information:
  • Show/hide specific elements
  • Toggle status indicators
  • Configure display modes (compact, detailed, etc.)
Customize the widget’s header:
  • Set a custom title
  • Choose a custom icon
  • Show/hide the header entirely

​
Widget-Specific Settings

Each widget type has unique configuration options: Media Server Widget:
  • Show recently added items
  • Display library statistics
  • Enable/disable status indicators
System Resources Widget:
  • Select which resources to monitor (CPU, RAM, network)
  • Configure warning thresholds
  • Choose chart styles
Weather Widget:
  • Set location
  • Choose temperature units (Celsius/Fahrenheit)
  • Select forecast duration
RSS Feed Widget:
  • Add multiple feed URLs
  • Set maximum items to display
  • Configure update frequency

​
Advanced Customization Options

​
Advanced Options Modal

For advanced customization, click Advanced Options in the widget settings modal:
1

Custom CSS Classes

Add custom CSS classes to style the widget:
custom-shadow
highlight-border
dark-theme-override
These classes can be defined in your theme or custom CSS file.
2

Border Color

Set a custom border color for the widget. This helps visually group related widgets or highlight important information.Use hex color codes (e.g., #FF5733) or color names.
Advanced options are preserved when duplicating or moving widgets between boards.

​
Widget Status Indicators

Many widgets display status indicators showing the health of connected services:
  • Green: Service is online and responding
  • Yellow: Service is responding but may have issues
  • Red: Service is offline or not responding
  • Gray: Status check is disabled
You can configure status checking behavior in the server settings:
  • Enable/disable status checks globally
  • Set check intervals
  • Force disable status checks for performance

​
Duplicating and Removing Widgets

​
Duplicating a Widget

To quickly create a copy of an existing widget:
  1. Enter edit mode
  2. Click the More Options menu (three dots) on the widget
  3. Select Duplicate
  4. The duplicated widget appears next to the original with identical settings
Duplicated widgets share the same configuration but are independent - changes to one won’t affect the other.

​
Removing a Widget

To remove a widget from your board:
  1. Enter edit mode
  2. Click the More Options menu (three dots) on the widget
  3. Select Remove
  4. Confirm the deletion
Removing a widget is permanent and cannot be undone. The widget and its configuration will be deleted from the board.

​
Widget Sections and Categories

Widgets can be organized into sections (categories) on your board:

​
Creating Sections

  1. Enter edit mode
  2. Click Add Section
  3. Name your section (e.g., “Media Services”, “System Monitoring”)
  4. Configure section settings:
    • Collapsible/expanded by default
    • Section icon
    • Section color

​
Moving Widgets Between Sections

Drag widgets between sections to reorganize your board. The widget will automatically be added to the section where you drop it.

​
Section Management

Sections can be:
  • Reordered by dragging their headers
  • Collapsed/expanded to save space
  • Deleted (removes all widgets within)
  • Renamed at any time

​
Best Practices

Performance

  • Don’t overcrowd boards with too many widgets
  • Use reasonable refresh intervals
  • Disable status checks for widgets you don’t need to monitor

Organization

  • Group related widgets in sections
  • Use consistent naming conventions
  • Keep frequently used widgets at the top

Visual Design

  • Use border colors to highlight important widgets
  • Keep widget sizes consistent within sections
  • Balance information density with readability

Integration

  • Set up integrations before adding widgets
  • Test integrations independently first
  • Use descriptive integration names

​
Troubleshooting

This widget requires an integration to function. Edit the widget settings and select an appropriate integration from the dropdown.
Common causes:
  • Integration is offline or misconfigured
  • Invalid credentials or API key
  • Network connectivity issues
Check the integration settings and ensure the service is accessible from your Homarr instance.
Make sure you’re in edit mode. Click the Edit button in the top-right corner of the board.
  • Ensure you click Save in edit mode before exiting
  • Check browser console for errors
  • Verify you have permission to edit the board

​
Next Steps

Explore Widgets

Learn about all available widget types and their capabilities

Set Up Integrations

Configure integrations to power your widgets

Customize Boards

Learn about board layouts and customization options

Troubleshooting

Get help with common issues

Build docs developers (and LLMs) love

Get started for freeTalk to us