Dashboard Pages

Wix Apps can extend the Wix Dashboard by adding new pages to the dashboard. You can create a dashboard page to help users manage their sites or businesses. Dashboard pages aren’t part of a live site, so site visitors will never see them.

Dashboard page files

Within your app project, the source code for dashboard pages is found in the src/dashboard/pages folder.

Each page is defined in its own subfolder that contains two files:

The location of the page's subfolder determines the route to the page.

Page metadata (page.json)

The page.json file contains the dashboard page metadata.

The page metadata is defined using the following schema, shown here as a TypeScript type:

Copy
1
type BackOfficePageConfig = {
2
  id: string;
3
  title: string;
4
  additionalRoutes?: string[];
5
  sidebar?: {
6
    disabled?: boolean;
7
    categoryId?: string;
8
    priority?: number;
9
    whenActive?: {
10
      selectedPageId?: string;
11
      hideSidebar?: boolean;
12
    };
13
  };
14
};

Here's an example metadata definition:

Copy
1
{
2
  "id": "15a6e3ad-620e-416b-840d-367be43a4fd8",
3
  "title": "My CLI App Page",
4
  "sidebar": {
5
    "categoryId": "041e3b2a-d25b-47ce-8162-dfdfe0e64785",
6
    "whenActive": {
7
      "hideSidebar": true
8
    }
9
  }
10
}

id

The page ID (GUID). The ID is used to register the page in Wix Developers Center. The ID must be unique across all pages in the app.

title

The page title. The title is used as the browser tab title and as the dashboard sidebar label if the page is configured to appear in the sidebar.

additionalRoutes (optional)

A list of routes that lead to this page (in addition to the main route defined by the file path convention). This is useful if you want to support multiple routes for the same page or for backwards compatibility.

For example, if you want both /products and /products/list to lead to the same page.

sidebar (optional)

An object that defines the behavior of this page in the dashboard sidebar.

sidebar.disabled (optional)

Whether the page is shown in the sidebar. If true, the page is not shown in the sidebar. Defaults to false.

sidebar.categoryId (optional)

The ID of the category to associate this page with, as defined in the sidebar categories configuration.

sidebar.priority (optional)

The priority of the page entry in the sidebar. Determines the page location in relation to other app pages. Smaller numbers mean higher priority.

sidebar.whenActive.selectedPageId (optional)

When the page is the currently active page, this setting determines the page that is selected in the sidebar.

You can use this you have a page that is a nested page and doesn’t have an entry in the sidebar, but you want the sidebar to display some page as active.

For example, you might have a number of pages for a specific products. You don't want these pages cluttering up the sidebar, so you set them not to display there. However, when one of the product pages is active, you might want the products list page to be selected in the sidebar.

Defaults to the current page.

sidebar.whenActive.hideSidebar (optional)

Whether the sidebar will be shown when the page is active. If true, the sidebar is hidden when the page is active. Defaults to false.

Hiding the sidebar creates a more immersive experience by gaining more screen real estate.

Page content (page.tsx)

The page.tsx file contains the dashboard page content.

The content is defined as a React component that renders when the page is active.

Inside a dashboard page component you can use:

  • The Dashboard SDK to navigate users to pages in the dashboard, display modals, and send users alerts and updates using toasts.
  • The Wix Design System to use the same React components Wix uses to build its own dashboard pages.

Page Routes

The location of a dashboard page files within the src/dashboard/pages folder determines the route to the page. The route is the path that is appended to the dashboard base URL to access the dashboard page. Therefore, you should name your page folders using URL-friendly names.

To create longer routes, nest page.json files inside of subfolders.

For example, consider this folder structure:

Copy
1
src
2
└── dashboard
3
    └── pages
4
        ├── products
5
        │   ├── page.json
6
        │   ├── page.tsx
7
        │   └── analytics
8
        │       ├── page.json
9
        │       └── page.tsx
10
        ├── orders
11
        │   ├── page.json
12
        │   └── page.tsx
13
        ├── page.json
14
        └── page.tsx

This app adds 4 pages to the dashboard:

  • Index page (dashboard/pages/page.json) - Route: /
  • Products page (dashboard/pages/products/page.json) - Route: /products
  • Analytics page (dashboard/pages/products/analytics/page.json) - Route: /products/analytics
  • Orders page (dashboard/pages/orders/page.json) - Route: /orders

Sidebar Categories

The dashboard sidebar is divided into categories. Each category is defined by a category ID and a category label. The category ID is used to associate pages with a specific category. The category label is used as the display label of the category under which all the pages that belong to that category can be found.

Category Configuration

The wix.config.json file in the root of the app project defines your app's sidebar categories.

The categories are defined using the following schema, shown here as a TypeScript type:

Copy
1
type WixConfigJSON = {
2
  // ... other configurations
3
  dashboard?: {
4
    sidebar?: {
5
      categories?: Array<SidebarCategory>;
6
    };
7
  };
8
};
9


10
type SidebarCategory = {
11
  id: string;
12
  label: string;
13
  priority?: number;
14
};

Here's an example configuration:

Copy
1
"dashboard": {
2
  "sidebar": {
3
    "categories": [{
4
      "id": "041e3b2a-d25b-47ce-8162-dfdfe0e64785",
5
      "label": "My CLI App"
6
    }]
7
  }
8
}

SidebarCategory

id

The category ID (GUID). The ID is used as a reference to the category from page configurations. The ID must be unique across all categories in the app.

label

The text to display as the category label in the sidebar.

priority (optional)

The priority of the category in the sidebar. Determines the category location in relation to other app categories. Smaller numbers mean higher priority.

Add a new dashboard page

To add a new dashboard page to your app:

  1. Create a new subfolder under src/dashboard/pages that will determine the route of your page.
  2. Add a new set of page.json and page.tsx dashboard page files to the subfolder you created.
  3. Add the page metadata to the page.json file.
  4. Add the page code to the page.tsx file.

Delete a dashboard page

To delete an existing dashboard page from you app, delete the subfolder under src/dashboard/pages that contains your dashboard page's files.

Note: If you've already created a version of your app, deleting a dashboard page's files from your project will not remove the registration of the dashboard page from the Wix Developers Center. To remove the registration, create a new version after deleting the dashboard page's files.

Was this helpful?
Yes
No