feat: complete automatic mobile board UX

2026-07-28 19:39:13 +02:00
1 parent cf83e0d849
commit 7959c20d88
@@ -80,6 +80,9 @@ The OpenAPI and MCP APIs include board management endpoints for common automatio
 - Change board visibility
 - Update board visual and behavior settings
 - Set desktop and mobile home boards for the current user
- Configure global board defaults such as public home boards and status behavior
+- Configure global board defaults such as public home boards, automatic mobile layout mode, and status behavior
+- Configure saved responsive layouts through Homarr's board settings UI when a server uses legacy mobile layout mode

-Use the interactive API reference to inspect the exact request body for each endpoint under the `boards` and `settings` tags.
+Use the interactive API reference to inspect the exact request body for OpenAPI endpoints under the `boards` and
+`settings` tags. Saved responsive layouts are intentionally not exposed as an OpenAPI or MCP replacement operation
+because omitting a layout would remove it.
@@ -84,23 +84,29 @@ Homarr will fall back to the Homarr logo if nothing is set.

 ### Layout

-In this section you can configure the number of columns in the desktop layout.
+The available controls depend on the server-wide **Use automatic mobile layout** setting under `Management` > `Settings` > `Boards`.

 Items and sections can be moved and resized on desktop while the board is in edit mode.
 Changing the column count automatically adjusts item positions and sizes to fit the new grid.

 <img src={layoutLargeImage} height={256} />

-#### Mobile layout
+#### Automatic mobile layout

-Phones use an automatic, read-only layout with exactly two columns in both portrait and landscape. Tablets use this layout at widths up to 48em. Items follow the visual order of the desktop layout and are limited to two columns wide and three rows high.
+When automatic mobile layout is enabled, the board settings contain one desktop column-count control. Phones use an automatic, read-only layout with exactly two columns in both portrait and landscape. Tablets use this layout at widths up to 48em. Items follow the visual order of the desktop layout and are limited to two columns wide and three rows high.

-Named categories and dynamic sections appear as lightweight headings and section shortcuts, but never as layout containers. Their items are included directly in the automatic grid, even when a category is collapsed on desktop. Layout and widget configuration stay locked on mobile; links, refresh actions, automations, and widget details remain interactive.
+Named categories and dynamic sections appear as lightweight headings and section shortcuts, but never as layout containers. Their items are included directly in the automatic grid, even when a category is collapsed on desktop. Layout and item-configuration menus stay locked on mobile; links, refresh actions, automations, notebook content and checklists, and widget details remain interactive according to the user's normal permissions.

 App items use compact tiles. Widgets can opt into a compact summary, and larger widgets provide a full-screen detail view. Widgets farther down a long board are loaded shortly before they enter the viewport while their space is preserved with a skeleton.

 To rearrange, add, remove, resize, or configure board items, open the board on a larger screen.

+#### Saved responsive layouts
+
+When automatic mobile layout is disabled, each board uses its saved responsive layouts. Board editors can add named layouts, choose their column counts and viewport breakpoints, and edit the selected layout directly on mobile.
+
+Enabling automatic mode does not delete these layouts. Homarr continues to maintain item and section placements for them, so an administrator can switch the server back to responsive mode later without losing the previous mobile arrangement.
+
 ### Background

 #### Background image URL
@@ -9,10 +9,12 @@ tags:
 ---

 # Settings
+
 The settings page has a few options that will be applied to the entire Homarr application.
 They may require a full page reload for changes to apply.

 ## Analytics
+
 By default, Homarr is collecting anonymous analytics to identify issues and prioritize bugfixes and improvements.
 The data is never shared with any third-parties and is fully GDPR & CCPA compliant.
 The software being used is [Umami Analytics](https://umami.is/) which is fully open source.
@@ -21,25 +23,29 @@ The main server software can be found [here](https://github.com/umami-software/u
 A full list of the collected data by default can be found here: https://umami.is/docs/metric-definitions.

 We understand that you might not want Homarr to communicate with our services.
-By unchecking the ``Send anonymous analytics`` checkbox and reloading the full page, all communication by Umami will be disabled and no data will be collected.
-If you are paranoid, you can permanently block ``umami.homarr.dev`` from your DNS / firewall.
+By unchecking the `Send anonymous analytics` checkbox and reloading the full page, all communication by Umami will be disabled and no data will be collected.
+If you are paranoid, you can permanently block `umami.homarr.dev` from your DNS / firewall.

 Additionally, you opt in to more data collection to help us provide more useful data.

 ### Integration data
+
 Enabling this optional data will send the types of integrations (e.g. SABnzbd, Sonarr, ...) and how many you have configured of them.
 This will not include any URLs, names, secrets, errors and others. This is disabled by default.

 ### Widget data
+
 Enabling this optional data will send the types of widgets (e.g. downloads, media streams, iframe, ...) and how many you have configured of them.
 This will not include any URLs, names, secrets, errors and others. This is disabled by default.

 ### Users data
+
 Enabling this optional data will send the count of users and whether you activated SSO.
 This will not include any usernames, passwords, emails, URLs, authentication flows or client IDs.
 This is disabled by default.

 ## Search Engine Optimization (SEO)
+
 Big companies [like Google, Microsoft, Baidu and Yandex](https://de.wikipedia.org/wiki/Web-Index) will use [web crawlers](https://de.wikipedia.org/wiki/Webcrawler) to index the Internet for new websites & pages.
 This is desirable in many cases (for example when selling products in an online shop) but can lead to unwanted traffic and attention to your personal dashboard.
 Homarr is requesting the crawlers to not index Homarr instances by default for this reason.
@@ -47,22 +53,26 @@ If you use Homarr as a public website and want it to be searchable on these sear
 Please note that Homarr doesn't have control over what the crawlers do; it is a mere request to them to not perform these actions but will not guarantee that your website doesn't land on some index.

 ### No index
+
 This will ask crawlers to not index your Homarr instance on any indexes.
 It is up to the crawler to properly respect this request.
 By default, this setting is enabled. Disabling it will allow indexing.

 ### No follow
+
 If indexing is allowed, crawlers will also attempt to follow any links on your page to further "discover" new parts of the Internet and on your website.
 By default, this setting is enabled and will ask crawlers to not follow any links.
 Crawler of different companies may behave differently when indexing is prohibited and following is allowed.

 ### No translate
+
 Google and Chrome on Android will prompt users to translate pages that are not in their device language.
 This can lead to some shifting and can be undesired in some cases. By enabling this,
 you ask crawlers to never translate and never prompt users for translation.
 It should be noted that some browsers will ignore this and translate regardless.

 ### No site links search box
+
 This setting is exclusive to Google.
 [Google will create a box below your domain](https://developers.google.com/search/docs/appearance/structured-data/sitelinks-searchbox) that lists the paths that were discovered by the "folowing".
 The user can search them directly in Google.
@@ -71,8 +81,22 @@ This setting is disabled by default.

 ## Boards

+### Automatic mobile layout
+
+**Use automatic mobile layout** controls mobile rendering for every board on the server:
+
+- Enabled: phones and small tablets use Homarr's read-only, two-column mobile view. Mobile layout editing is hidden.
+- Disabled: boards use their saved responsive layouts and users with board modification access can edit layouts on mobile.
+
+This setting is enabled by default for new instances. During an upgrade, Homarr keeps it disabled when it detects existing custom responsive layouts, including boards with multiple layouts or a non-default saved layout. Instances that only contain the canonical desktop layout use the new automatic mode. Once an administrator saves an explicit choice, later upgrades preserve it.
+
+Saved responsive layouts are retained while automatic mode is enabled, so switching between the modes is reversible. Reload any board tabs that were already open when the setting changed.
+
+The automatic-layout setting is independent from the global mobile board below: one controls how a board is rendered, while the other controls which board opens on a detected mobile device.
+
 ### Global home board
-You can set a global home board that will be used for all users that have not set a home board themselves. 
+
+You can 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.
 Note that the board must be public to be used as a global home board.

@@ -97,9 +121,11 @@ You can decide if the app status should be disabled for all boards.
 ## Appearance

 ### Default color scheme
+
 You can set the default color scheme for all users that have not set a color scheme themselves.

 ## Culture

 ### Default language
-You can set the default language for all users that have not set a language themselves.
+
+You can set the default language for all users that have not set a language themselves.