Skip to main content
Boards are the foundation of Homarr - customizable dashboards that organize your applications, services, and widgets in a visual layout. Each board can be tailored to specific needs, whether it’s monitoring your home lab, managing media services, or tracking development projects.

​
What are Boards?

A board is a customizable dashboard that contains:
  • Widgets: Interactive components displaying real-time data
  • Apps: Quick access links to your services
  • Custom layouts: Responsive grid system that adapts to different screen sizes
  • Background customization: Personalize with images and themes
  • Permission controls: Share with specific users or groups

​
Creating a Board

Create a new board from the Boards page:
  1. Navigate to the boards overview
  2. Click New Board
  3. Enter a name for your board
  4. Configure initial settings:
    • Public/Private visibility
    • Background image
    • Default layout settings
Board names must be unique and will be used in the URL (e.g., /board/home)

​
Layout System

Homarr uses a responsive grid system that automatically adapts to different screen sizes. Boards support multiple layout breakpoints:

​
Breakpoints

The board automatically selects the appropriate layout based on window width: 
// Example from packages/boards/src/context.tsx:76
const sortedLayouts = board.layouts.sort((layoutA, layoutB) => 
  layoutB.breakpoint - layoutA.breakpoint
);

const currentLayout = sortedLayouts.find(
  (layout) => layout.breakpoint <= window.innerWidth
);
This ensures your board looks great on:
  • Desktop monitors (1920px+)
  • Laptops (1280px-1920px)
  • Tablets (768px-1280px)
  • Mobile devices (less than 768px)

​
Grid System

Widgets and apps are positioned using a drag-and-drop grid:
  • Columns: Configurable number of columns per breakpoint
  • Rows: Automatic based on content
  • Widget sizing: Width and height in grid units
  • Auto-positioning: Items snap to grid for perfect alignment
Enable edit mode to customize your board:
  1. Click the Edit button in the top right
  2. Drag widgets to reposition them
  3. Resize widgets using corner handles
  4. Add new widgets from the widget menu
  5. Click Save to persist changes
// Edit mode state (packages/boards/src/edit-mode.tsx:10)
const EditModeProvider = ({ children }) => {
  const editModeDisclosure = useDisclosure(false);
  return <EditModeContext.Provider value={editModeDisclosure}>
    {children}
  </EditModeContext.Provider>
};

​
Customizing Boards

​
Background Images

Personalize your board with custom backgrounds:

Image Options

  • Attachment: Fixed or scroll with page
  • Repeat: Control image tiling
  • Size: Cover or contain
  • Opacity: Adjust background transparency

Supported Formats

  • JPEG/JPG
  • PNG
  • WebP
  • SVG
  • GIF (static or animated)
// Background image options (packages/definitions/src/board.ts)
const backgroundImageAttachments = ["fixed", "scroll"];
const backgroundImageRepeats = ["repeat", "repeat-x", "repeat-y", "no-repeat"];
const backgroundImageSizes = ["cover", "contain"];

​
Board Settings

Access board settings from the board menu:
  • Name: Change the board name and URL
  • Visibility: Toggle public/private access
  • Permissions: Manage user and group access
  • Background: Configure background images
  • Layout: Adjust grid columns for each breakpoint

​
Board Permissions

Control who can access and modify your boards with granular permission levels:

​
Permission Levels

Users can see the board and interact with widgets, but cannot make changes.
  • Read-only access to all board content
  • Can use widgets and click apps
  • Cannot edit layout or settings
Granted when:
  • Board is public, OR
  • User has explicit view permission, OR
  • User belongs to a group with view permission
Users can edit the board layout, add/remove widgets, and configure widget settings.
  • All view access capabilities
  • Add and remove widgets
  • Rearrange layout
  • Configure widget options
  • Cannot change board permissions or delete the board
Granted when:
  • User has explicit modify permission, OR
  • User belongs to a group with modify permission, OR
  • User has board-modify-all permission
Complete control over the board including permissions and deletion.
  • All modify access capabilities
  • Change board settings
  • Manage permissions for other users
  • Delete the board
Granted when:
  • User is the board creator, OR
  • User has explicit full permission, OR
  • User belongs to a group with full permission, OR
  • User has board-full-all permission

​
Permission Implementation

// From packages/auth/permissions/board-permissions.ts:24
const constructBoardPermissions = (board, session) => ({
  hasFullAccess:
    isCreator ||
    board.userPermissions.some(({ permission }) => permission === "full") ||
    board.groupPermissions.some(({ permission }) => permission === "full") ||
    session?.user.permissions.includes("board-full-all"),
    
  hasChangeAccess:
    isCreator ||
    board.userPermissions.some(({ permission }) => 
      permission === "modify" || permission === "full") ||
    board.groupPermissions.some(({ permission }) => 
      permission === "modify" || permission === "full") ||
    session?.user.permissions.includes("board-modify-all"),
    
  hasViewAccess:
    isCreator ||
    board.userPermissions.length >= 1 ||
    board.groupPermissions.length >= 1 ||
    board.isPublic ||
    session?.user.permissions.includes("board-view-all")
});

​
Sharing Boards

​
Public Boards

Make boards accessible to all users:
  1. Open board settings
  2. Enable Public Access
  3. Save changes
Public boards appear in the boards list for all users and can be accessed without authentication (if guest access is enabled).

​
User-Specific Permissions

Grant access to individual users:
  1. Open board settings → Permissions
  2. Click Add User
  3. Select the user
  4. Choose permission level (View, Modify, or Full)
  5. Save changes

​
Group Permissions

Share with multiple users at once:
  1. Open board settings → Permissions
  2. Click Add Group
  3. Select the group
  4. Choose permission level
  5. Save changes
All users in the group automatically inherit the permission level.
User-specific permissions override group permissions. If a user has both, the higher permission level applies.

​
Board Context

Boards maintain their state using React context, ensuring widgets always have access to the latest board data: 
// From packages/boards/src/context.tsx:12
const BoardContext = createContext<{
  board: RouterOutputs["board"]["getBoardByName"];
} | null>(null);

// Hooks for accessing board data
export const useRequiredBoard = () => {
  const context = useContext(BoardContext);
  if (!context) throw new Error("Board is required");
  return context.board;
};
This ensures all widgets on the board have consistent access to:
  • Board configuration
  • Current layout settings
  • Permission levels
  • Real-time updates

​
Best Practices

Organization

  • Create separate boards for different purposes (monitoring, media, development)
  • Use descriptive names that indicate the board’s function
  • Group related widgets together
  • Keep frequently accessed items near the top

Performance

  • Limit the number of widgets with real-time updates
  • Use appropriate refresh intervals
  • Optimize images for web (compress before uploading)
  • Test on target devices to ensure responsive layout works

Permissions

  • Start with private boards and add permissions as needed
  • Use groups for team-based access
  • Review permissions regularly
  • Keep sensitive data on restricted boards

Maintenance

  • Remove unused widgets to reduce clutter
  • Update widget configurations when services change
  • Archive old boards instead of deleting (if needed later)
  • Document complex setups for team members

​
Next Steps

Add Widgets

Learn about available widgets and how to configure them

Configure Integrations

Connect your services to enable widget functionality

Set Up Authentication

Configure user management and permissions

Search Features

Use search to quickly find services across boards

Build docs developers (and LLMs) love

Get started for freeTalk to us