381 lines
15 KiB
Plaintext
381 lines
15 KiB
Plaintext
---
|
||
title: Boards
|
||
tags:
|
||
- Management
|
||
- Boards
|
||
- Customization
|
||
- Edit mode
|
||
- Responsive
|
||
- Layout
|
||
---
|
||
|
||
import iconColorImage from "./img/icon-color.png";
|
||
import itemRadiusImage from "./img/item-radius.png";
|
||
import layoutLargeImage from "./img/layout-large.png";
|
||
import layoutMediumImage from "./img/layout-medium.png";
|
||
import layoutSmallImage from "./img/layout-small.png";
|
||
|
||
Each dashboard is called a "board".
|
||
You can create as many boards as you want.
|
||
Boards can be restricted to user groups.
|
||
A user may also have a "home board" which they will see at the root path (e.g. my-homarr.com or my-homarr.com/board).
|
||
Other boards can be viewed by direct links (e.g. my-homarr.com/board/smart-home) or via the management pages.
|
||
|
||
Names of boards must be unique because this will be used in the URL to load the desired board.
|
||
|
||
## Create a new board
|
||
|
||
When creating a board, the availability of the board name will be checked for you.
|
||
|
||
|
||
|
||
### Name
|
||
|
||
The name must not include any special characters and must be at least one character long.
|
||
Underscores and hyphen-minus are allowed.
|
||
|
||
### Column count
|
||
|
||
The column count defines how many fixed-width cells are available in each row.
|
||
One cell contains a `200 × 200` logical-pixel tile.
|
||
Homarr scales the whole board uniformly instead of changing widget proportions, with horizontal scrolling when further shrinking would make controls too small.
|
||
|
||
### Public
|
||
|
||
This will enable public access for everyone - regardless of whether they are logged in or not.
|
||
This can be really useful if you want to have public boards in your company or for family and friends.
|
||
Modifications for public boards must be allowed explicitly using user groups and their permissions.
|
||
|
||
## Board settings
|
||
|
||
You navigate to the board settings by clicking on these three dots:
|
||
|
||
|
||
|
||
Alternatively, you can also navigate from the board page itself using the cog icon at the top right:
|
||
|
||
|
||
|
||
All board settings are edited on a single page. Click the **Save changes** button in the save bar at the bottom to apply them, or **Discard** to restore the last saved values. The save bar only appears when you have unsaved changes. Access control and the Danger zone are independent sections and are applied immediately.
|
||
|
||
### General
|
||
|
||
#### Page title
|
||
|
||
This is the title that will be visible at the top left in the navigation bar:
|
||
|
||
|
||
|
||
This field is optional and Homarr will fall back to "Homarr" if nothing is set.
|
||
|
||
#### Meta title
|
||
|
||
This is the secondary title of the page that is not directly visible in the page itself.
|
||
Browser will use it to set the title of tabs:
|
||
|
||
|
||
|
||
Homarr will fall back to the board name and a suffix if nothing is set.
|
||
|
||
#### Logo image URL
|
||
|
||
This is the URL that is used for the image at the top left.
|
||
Homarr will fall back to the Homarr logo if nothing is set.
|
||
|
||
#### Favicon image URL
|
||
|
||
This is the URL that is used for the favicon in the tab title.
|
||
Homarr will fall back to the Homarr logo if nothing is set.
|
||
|
||
### Layout
|
||
|
||
In this section you can configure the different responsive layouts.
|
||
Homarr selects a layout from the screen width, then scales its complete fixed-size canvas uniformly.
|
||
|
||
|
||
|
||
Every `1 × 1` tile has a `200 × 200` logical-pixel content area.
|
||
The `24` logical-pixel gap between tiles is separate from that size.
|
||
A `2 × 1` tile therefore contains two fixed cell widths plus the gap between them.
|
||
Widgets see their logical size, while the board's visual scale makes the complete layout larger or smaller.
|
||
When fitting below 100%, Homarr keeps widget typography and control density at their normal readable size.
|
||
On larger canvases, the complete board grows together like browser zoom.
|
||
The scale never drops below 75%; on narrower screens the canvas scrolls horizontally instead of shrinking controls below an accessible size.
|
||
|
||
The position and size of every item are independent in each responsive layout.
|
||
Moving or resizing an item in one layout does not change any other layout.
|
||
When adding a new layout, its initial positions and sizes are generated from the column count.
|
||
New items use their widget's default grid size, while a new Container starts at a useful `4 × 3` size when the layout has enough columns.
|
||
Both are placed in the first available position.
|
||
|
||
The current board edge is a hard drag boundary, so moving a tile outside the canvas cancels that placement instead of creating empty rows.
|
||
Adding content can still create the rows required for the new tile.
|
||
Nested Containers keep their own resizable bounds.
|
||
|
||
#### Name
|
||
|
||
The name of the layout can be chosen freely. It is only used for management and will not be visible on the board.
|
||
|
||
#### Column count
|
||
|
||
Total number of columns for this layout.
|
||
When changed, Homarr moves items into the next available positions without overlap.
|
||
|
||
#### Fixed rails
|
||
|
||
Each responsive layout can enable a fixed left rail, a fixed right rail, or both.
|
||
Set a rail width to zero to disable it for that layout.
|
||
Choose a width from one to three columns with the three-step slider.
|
||
The preview shows how much space remains for the main canvas.
|
||
|
||
Rail columns are reserved from the layout's total column count.
|
||
For example, a 12-column layout with a two-column left rail leaves ten columns for the canvas.
|
||
Enabling or widening a rail reflows canvas items into the remaining columns.
|
||
Disabling a rail moves its contents back into the next available canvas positions.
|
||
|
||
Rails remain visible while the page scrolls.
|
||
Apps, widgets, and Containers inside them still use the same fixed `200 × 200` cells and can be rearranged in edit mode.
|
||
|
||
#### Breakpoint
|
||
|
||
Minimum width of the screen where the layout will be used.
|
||
Once the minimum of the next layout is reached, the layout will change.
|
||
|
||
#### View and edit modes
|
||
|
||
View mode renders a static board without executing the drag-and-drop editor.
|
||
After the board is interactive, Homarr prepares the editor in the background for users who can modify it.
|
||
Entering edit mode keeps the static board visible until that preparation finishes, then enables collision-aware movement and resizing without changing the board geometry.
|
||
Widget content is inert in edit mode, so dragging anywhere on the content moves the tile instead of activating the widget; its settings button remains visible in the compact header above the tile.
|
||
Dropping a tile into another tile's exact slot swaps their positions when both resulting placements fit without overlapping other content.
|
||
For other collisions, or when a tile grows into occupied space, nearby tiles are compacted out of the way.
|
||
The visible corner controls provide a 44-pixel resize target, and edge controls appear on hover for horizontal or vertical resizing.
|
||
Resize handles stop at the tile's minimum allowed size while the pointer is still moving.
|
||
Exit edit mode to save the resulting positions.
|
||
|
||
Pointer users can drag anywhere on a widget tile. Containers use the grab button at their top-left corner.
|
||
Resize tiles from any edge or corner handle.
|
||
On a touch screen, press and hold the tile before moving it; resize handles support direct touch input.
|
||
Keyboard users can focus a tile, press Enter or Space to start editing, use the arrow keys to move it, and use Shift plus the arrow keys to resize it.
|
||
Press Enter, Space, or Escape to stop keyboard editing.
|
||
Keyboard moves and resizes apply immediately; Escape stops keyboard editing without undoing those changes.
|
||
During a pointer or touch interaction, Escape cancels the move or resize and restores the layout from before that interaction.
|
||
The **Move / resize item** action in the edit menu remains available for precise numeric input.
|
||
|
||
#### Preview
|
||
|
||
<img src={layoutSmallImage} height={256} />
|
||
<img src={layoutMediumImage} height={256} />
|
||
<img src={layoutLargeImage} height={256} />
|
||
|
||
### Containers and rails
|
||
|
||
Containers can hold apps, widgets, and nested Containers.
|
||
The same Container model works on the main canvas, inside a fixed rail, or inside another Container.
|
||
Move and resize Containers directly in edit mode; nested content stays within the Container's local bounds.
|
||
Resize outlines follow the pointer continuously while a dashed preview marks the grid size that will be applied on release.
|
||
Each responsive layout stores its own Container position and size.
|
||
|
||
Each Container can configure:
|
||
|
||
- Its label and whether that label is visible.
|
||
- Whether users can collapse and expand it like an accordion.
|
||
- Whether its menu shows **Open all in new tabs** for the app links it contains.
|
||
- Its border color and custom CSS classes.
|
||
|
||
Collapsing a Container reduces its full-width header to a half-row expansion bar and compacts the surrounding layout without losing its expanded size.
|
||
Expanding it smoothly restores those bounds and moves following items out of the way without reloading the widgets inside it.
|
||
|
||
### Background
|
||
|
||
#### Background image URL
|
||
|
||
Homarr can display a background image behind apps and widgets.
|
||
This URL can be used to define what image should be shown.
|
||
|
||
#### Background image attachment
|
||
|
||
This defines whether the background should move when the user scrolls.
|
||
|
||
#### Background image size
|
||
|
||
This defines whether the background should cover the entire page (and possibly be cropped) or never be cropped but may not cover the entire page.
|
||
|
||
#### Background image repeat
|
||
|
||
This defines whether the background should be repeated if it cannot cover the entire page.
|
||
This option can be useful if you have patterns that can be repeated easily (e.g. patterns):
|
||
|
||
|
||
|
||
### Appearance
|
||
|
||
#### Primary color
|
||
|
||
Color that can be chosen freely to give accents to active elements.
|
||
|
||
#### Secondary color
|
||
|
||
Color that can be chosen freely to give accents.
|
||
|
||
#### Opacity
|
||
|
||
Opacity of the colors.
|
||
|
||
#### Icon color
|
||
|
||
Change the color of your bookmark / app icons.
|
||
|
||
<img src={iconColorImage} height={100} />
|
||
|
||
#### Item radius
|
||
|
||
Change the radius of your items and Containers.
|
||
|
||
<img src={itemRadiusImage} height={100} />
|
||
|
||
### Custom CSS
|
||
|
||
This is the field where you can enter custom CSS.
|
||
The styling will only be applied on the respective board page.
|
||
|
||
[See this guide on how to work with custom CSS](/docs/advanced/styling/).
|
||
|
||
### Behaviour
|
||
|
||
#### Disable app status
|
||
|
||
This will disable the status check for apps.
|
||
|
||
#### Work directly from the board
|
||
|
||
Widgets expose their routine controls without requiring edit mode:
|
||
|
||
- Hold `Shift` while hovering a widget that supports advanced view to expand it in place while the other widgets
|
||
remain visible but dimmed. Release `Shift` to close it. Focus that widget and press `Shift` + `Enter` to keep the view
|
||
open until you close it. On touch devices, open it from the widget menu. Other widgets adapt in place instead.
|
||
- Right-click a widget to inspect its live query status, refresh its data, change quick options, open settings, or run
|
||
supported actions. Available controls follow your board and integration permissions.
|
||
- If you can modify the board, right-click or touch and hold an empty grid cell to add an item there. Focus a board
|
||
section and press `Shift` + `F10` for the keyboard equivalent.
|
||
|
||
Widget and empty-space context menus follow the **Enable right click on widgets** preference in your user settings.
|
||
|
||
### Access control
|
||
|
||
With the access control, you can permit a single user or a group to your board.
|
||
The users and groups can have one of these three levels of access:
|
||
|
||
| **Permission Level** | View board | Edit mode | Settings | Danger zone (eg. delete) |
|
||
| -------------------- | ---------- | --------- | -------- | ------------------------ |
|
||
| View board | X | | | |
|
||
| Modify board | X | X | X | |
|
||
| Full access | X | X | X | X |
|
||
|
||
The permission level can only be changed after adding the user / group:
|
||
|
||
|
||
|
||
If the board is private and the user is not added in any of the three tabs, they cannot access the board.
|
||
They also do not see the board on the start page nor do they have access to any links for the board.
|
||
|
||
Groups that have high permissions (e.g. administrator or all board permissions) will be shown as "inherited".
|
||
They are permitted implicitly due to their permissions.
|
||
|
||
After editing permissions, the save button below the table must be pressed.
|
||
Otherwise, all changes will be discarded.
|
||
|
||
### Danger zone
|
||
|
||
#### Rename
|
||
|
||
Renaming a board will break all existing links to it permanently with no redirect.
|
||
|
||
#### Board visibility
|
||
|
||
By default, boards will be private. This means only authenticated users that are authorized have access.
|
||
Making a board public will expose it to everyone - including unauthenticated users.
|
||
|
||
#### Delete
|
||
|
||
This will permanently delete the board.
|
||
This action is irreversible and cannot be undone.
|
||
|
||
## Delete boards
|
||
|
||
The deletion of boards is permanent and cannot be undone.
|
||
There are two ways to delete a board:
|
||
|
||
- Navigate to the settings of your board, open the "Danger zone" section and click on the "delete this board" button.
|
||
- Navigate to the list of boards in the management pages, click the three dots and click on "delete permanently".
|
||
|
||
Both actions will execute the same deletion process.
|
||
|
||
## Duplicate boards
|
||
|
||
:::note
|
||
Duplicating a board will not copy the users and groups that have access to the board
|
||
nor the integrations the user does not have access to.
|
||
:::
|
||
|
||
Duplicating a board will create a new board with the same settings and layout as the original board.
|
||
You can duplicate a board by clicking on the three dots in the list of boards and selecting "Duplicate board".
|
||
|
||
|
||
|
||
## Setting boards as your home board
|
||
|
||
The home board is the dashboard, that will be shown at the root path of Homarr or if no board name was passed in the URL.
|
||
All the following paths will lead to the home board:
|
||
|
||
- `my-homarr.com`
|
||
- `my-homarr.com/boards`
|
||
|
||
Your home board will have a special small badge at the top right in the list of boards:
|
||
|
||
|
||
|
||
### For yourself
|
||
|
||
To set the home board yourself, the easiest option is to set it directly in the list of boards:
|
||
|
||
|
||
|
||
Alternatively, you can also define it via your user profile:
|
||
|
||
1. Click on your user profile at the top right
|
||
2. Click on `Your preferences`
|
||
3. Change the home board in the `home board` dropdown and click on `Save`.
|
||
|
||
### For other users
|
||
|
||
1. Navigate to the users: `Management` > `Users` > `Manage`
|
||
2. Click on the username of the user that you want to adjust
|
||
3. Select the desired home board via the dropdown and click on `Save` \
|
||
|
||
|
||
### For user groups
|
||
|
||
1. Navigate to the user groups: `Management` > `Users` > `Groups` > `Manage`
|
||
2. Go to tab `Settings`
|
||
3. Select the desired home board via the dropdown and click on `Save` \
|
||
|
||
|
||
### For whole server
|
||
|
||
You can also set a global home board that will be used for all users that have not set a home board themselves.
|
||
It will also be used for anonymous users.
|
||
|
||
1. Navigate to the settings: `Management` > `Settings` > `Boards`
|
||
2. Select the desired home board via the dropdown and click on `Save` \
|
||
|
||
|
||
:::note
|
||
For the global home board you can only select boards that are public.
|
||
:::
|
||
|
||
### Mobile home board
|
||
|
||
Same as the home board, you can also set a mobile home board.
|
||
It will be used for devices that are detected as mobile devices. (Using User-Agent header)
|