Skip to content
AntFabric Corev1.0.0local

Navigation layouts

An organisation chooses how its apps’ navigation looks: an icon rail, a sidebar with labels and groups, or a top bar. The choice belongs to the shell, never to plugins. Plugins describe what they offer — menu entries, screens, badges — and work unchanged in every layout.

Level Where When it applies
Default Instance file: appearance.navigation From the first start, until an administrator changes it
The organisation’s choice App Admin → Appearance, stored in instance_settings (appearance.navigation) From then on; overrides the instance file

The same pattern as the instance file’s plugin configuration: the file sets the starting point, and after that the organisation’s administrators own it. Every layout ships in every build, so changing it needs no rebuild.

# instances/<id>.yaml
appearance:
navigation: sidebar # rail (default) | sidebar | top
  1. Codegen writes the instance file’s value into instance.generated.ts, so the first paint uses the default without waiting for the server.
  2. On start-up the apps read the organisation’s choice from a public core endpoint (it is needed before sign-in), keep it for the next start, and switch if it differs.
  3. The shell renders the chosen layout around the routes:
const Navigation = NAVIGATION_LAYOUTS[appearance.navigation] ?? NAVIGATION_LAYOUTS.rail;
<Navigation entries={entries} /> // the same entries for every layout
<main>{routes}</main>
Layout Shows Best for
rail Icons with short labels in a narrow column; badges on icons Few plugins; maximum room for workspace plugins (Chat, Sales)
sidebar Wide column with labels; core screens, then plugins under “Apps”; counts as pills; the rail on windows narrower than 900 px Many plugins; organisations that want grouping
top Horizontal menu; the app’s name left, bell and profile right; entries that do not fit the window go into “More” (re-measured on resize); groups become dropdowns in step 4 Organisations used to web portals

All three show core’s own entries (home, notifications, profile) in the same places, and the same badges.

Menu entries gain two optional fields, so existing plugins keep working:

surfaces:
web:
nav:
- {
id: sales.home,
label: Sales,
icon: briefcase,
path: '',
group: Work,
order: 20,
}
Field Used by Default
group Sidebar sections, top-bar dropdowns No group (top level)
order Position within the group The plugin order (below)

Every app lists plugins in one order: Home and the menu in the user app (web and desktop), the plugin pages in App Admin’s menu, and Home on the phone.

Level Where When it applies
Default The order of plugins: in the instance file From the first start, until an administrator changes it
The organisation’s choice App Admin → Appearance → Plugin order, stored in instance_settings (appearance.pluginOrder) From then on; “Use the default” goes back to the file

Dependencies do not change it: the server still loads a plugin after the plugins it depends on, but what people see follows this order. A plugin installed after the order was saved goes last; one removed drops out. The apps read the order with the layout (GET /api/v1/appearance, field pluginOrder), so changing it needs no rebuild; the web apps redraw at once, the phone on its next start.

Administrators may later hide entries in App Admin; the shell applies that over what plugins declare.

  • Never assume where the menu is or how wide the content area is. Use UI kit components that adapt. layout: 'workspace' means “the whole content area”, whatever its size.
  • No top-level navigation of your own. Tabs inside your plugin (Pipeline, Today, Meetings) belong to its content and are fine.
  • Check every layout. Switch it in App Admin → Appearance (a development switcher is step 4).
  • Desktop wraps the user app and follows the same setting.
  • Phone keeps its own pattern — home screen and bottom tabs — because a sidebar or top bar does not suit a phone. group and order order its entries too.
Piece Path
Instance file field and validation libs/plugin-manifest (instanceSchema.appearance), written into INSTANCE.appearance by codegen
Shared type @antfabric/contracts-core (NAVIGATION_LAYOUTS, Appearance)
Server apps/backend/src/appearance/ (service, public and admin controllers), migration 0016_appearance.sql
Client useNavigationLayout(default) and useOrderedPlugins(plugins, INSTANCE.plugins ids) in @antfabric/sdk-web (one request for both); NavigationLayoutView and layouts/ in @antfabric/app-shell: column.tsx (rail and sidebar), top.tsx (top bar)
Apps apps/web (and the desktop app around it) passes INSTANCE.appearance.navigation; App Admin and the App Manager are fixed to the rail (navigation="rail")
Piece Is
instance_settings key appearance.navigation The organisation’s choice; absent means the instance file’s default
instance_settings key appearance.pluginOrder The organisation’s plugin order; absent means the instance file’s order
Public read endpoint Returns the effective appearance (choice, else default); no sign-in
Admin endpoints PUT /admin/appearance (layout), PUT /admin/appearance/plugin-order (every installed plugin once, or null); permission appearance:configure (role admin); audited
App Admin → Appearance A preview of each layout and a save button; the plugin order with move up and down
Step What Visible change State
1 Move today’s rail into libs/app-shell/src/layouts/rail.tsx; add appearance to the instance file schema and codegen; the setting, endpoints and permission None Done
2 Sidebar layout; App Admin → Appearance Organisations can switch to the sidebar Done
3 Top bar layout with overflow Third option Done
4 Optional group and order on menu entries; development layout switcher; docs and review checklist Grouped sidebars and dropdowns Next