Customizing Views

Views are pages in the Admin Panel, including the Dashboard, List View, and Edit View. A Custom View can replace a built-in view or add a new route. FrogBot supports:

Root Views
Collection Views
Document Views

Configuration

Replacing Views

Use admin.components.views to replace a root view:

import { buildConfig } from 'frogbot'

export default buildConfig({
  admin: {
    components: {
      views: {
        dashboard: {
          Component: '/components/Dashboard#Dashboard',
        },
      },
    },
  },
})

You can replace the complete dashboard view or configure the modular Dashboard with widgets.

Adding New Views

Use any unique key and provide at least Component and path:

import { buildConfig } from 'frogbot'

export default buildConfig({
  admin: {
    components: {
      views: {
        reports: {
          Component: '/components/ReportsView#ReportsView',
          path: '/reports',
          exact: true,
        },
      },
    },
  },
})

View options

Each admin.components.views entry is an AdminViewConfig:

Option	Type	Default	Description
`Component`	`FrogBotComponent`	Required	Component rendered for the route. It receives `AdminViewServerProps`.
`path`	`/${string}`	None	Route relative to the admin route, beginning with `/`. Dynamic segments such as `/reports/:id` are supported. Required for new views; without it the view never matches. `account` and `dashboard` replacements keep their built-in routes when it is omitted.
`exact`	`boolean`	`false`	Match only the exact pathname. Without it, the view also matches nested paths such as `/reports/2024`.
`strict`	`boolean`	`false`	Treat a trailing slash as significant when matching.
`sensitive`	`boolean`	`false`	Match path casing.
`meta`	Page metadata	Root `admin.meta`	Metadata for this route, merged over the root page metadata. Values set here win. Without a title here or in `admin.meta.title`, a view other than `account` and `dashboard` gets the site name as its title (`admin.meta.openGraph.siteName`, `FrogBot` by default) with no suffix. Its Open Graph title, description, and keywords default to the title text. See Top-bar label for the tab title.

Routes cascade. Without exact, a route also matches paths that begin with its path. Register a more specific nested route before its parent route.

Building Custom Views

Root views receive AdminViewServerProps. The FrogBot request is nested at initPageResult.req. The following complete view keeps the standard navigation and page layout, requires an authenticated user with Admin Panel access, and uses the framework-issued request expected by DefaultTemplate:

import { notFound, redirect } from 'next/navigation'

import { DefaultTemplate } from '@frogbotai/ui/admin/rsc'
import type { AdminViewServerProps } from 'frogbot'

export function ReportsView({
  initPageResult,
  params,
  searchParams,
  user,
}: AdminViewServerProps) {
  const { permissions, req, visibleEntities } = initPageResult

  if (!req.user) {
    redirect('/login')
  }

  if (!permissions.canAccessAdmin) {
    notFound()
  }

  return (
    <DefaultTemplate
      req={req}
      i18n={req.i18n}
      locale={initPageResult.locale}
      params={params}
      permissions={permissions}
      searchParams={searchParams}
      user={user}
      visibleEntities={visibleEntities}
    >
      <main style={{ margin: '0 auto', maxWidth: 1200, padding: '2rem' }}>
        <h1>Reports</h1>
        <p>Signed in as {req.user.email}</p>
      </main>
    </DefaultTemplate>
  )
}

Use initPageResult.req.user and initPageResult.permissions for authorization. The top-level user prop is filtered for display and should not decide access.

Top-bar label

FrogBot clears the top-bar label every time the admin path changes. A view that sets no label shows only the logo, never the label of the page the user came from. To show a label, render SetStepNav from @frogbotai/ui/admin anywhere in the view, for example inside DefaultTemplate in the view above:

import { SetStepNav } from '@frogbotai/ui/admin'

export function ReportsStepNav() {
  return <SetStepNav nav={[{ label: 'Reports' }]} />
}

Each item takes a label and an optional url, which turns that segment into a link. In a client component, call setStepNav from useStepNav() inside a normal useEffect, not a useLayoutEffect: FrogBot clears the label in a layout effect, so a label set there is cleared again. If a view stays mounted while the path changes, include the path in the effect’s dependencies so the label is set again. The browser tab reads {last label part} {titleSuffix} and follows label changes live. The suffix comes from admin.meta.titleSuffix and defaults to - FrogBot, so this example shows Reports - FrogBot. An empty or non-text label keeps the page’s default tab title. On phones with the navigation menu closed, only the last label part shows. Long labels shorten with an ellipsis and leave room for the menu button. Before scripts load, the tab shows the view’s server title. A view without meta.title shows only the site name, admin.meta.openGraph.siteName or FrogBot by default, without the suffix. To show the label from the first paint, add meta: { title: 'Reports' } to the view configuration under admin.components.views. Use the same text as the label; FrogBot appends the configured title suffix, or the view’s own meta.titleSuffix when it sets one. meta.title also becomes the Open Graph title, description, and keywords unless the view or admin.meta sets them. A view whose path is under /settings gets the Settings area’s server title instead, such as Settings - FrogBot, while the built-in Settings view is in use. FrogBot replaces that view’s title, Open Graph title, description, and keywords. Register app views outside /settings, or add a settings page. Put page controls in the page body, not in the top bar.

Root Views

Root views are scoped directly under the Admin Panel mount. account and dashboard replace built-in views; any other key can register a new route.

export default buildConfig({
  admin: {
    components: {
      views: {
        account: {
          Component: '/components/AccountView#AccountView',
        },
        reports: {
          Component: '/components/ReportsView#ReportsView',
          path: '/reports',
          exact: true,
        },
      },
    },
  },
})

Collection Views

Collection views are scoped to a collection’s list and document routes. Configure them on the collection:

import type { CollectionConfig } from 'frogbot'

export const Posts: CollectionConfig = {
  slug: 'posts',
  fields: [{ name: 'title', type: 'text' }],
  admin: {
    views: [
      {
        type: 'custom',
        component: '/components/PostListView#PostListView',
      },
    ],
    components: {
      edit: {
        views: {
          default: {
            Component: '/components/PostEditView#PostEditView',
          },
        },
      },
    },
  },
}

admin.components.edit.views contains Document Views. Custom admin.views entries receive AdminViewServerProps; see List View for custom content and built-in list slots.

Start here

Basics

Managing Data

Features

Ecosystem

Deployment

Configuration

Replacing Views

Adding New Views

View options

Building Custom Views

Top-bar label

Root Views

Collection Views

​Configuration

​Replacing Views

​Adding New Views

​View options

​Building Custom Views

​Top-bar label

​Root Views

​Collection Views

Configuration

Replacing Views

Adding New Views

View options

Building Custom Views

Top-bar label

Root Views

Collection Views