roles

• Type: string[] | ((params: CallbackParams & { defaultRoles: string[] }) => string[])
• Optional: Yes

The roles property allows you to restrict the visibility of the list item to specific user roles. Like workspaces, this can be a static array or a function receiving the active desk context (workspace, currentUser, context) and the defaultRoles defined in your configuration.

Note

When using a static array, the provided values are concatenated with the defaultRoles. When using a callback function, the returned array is treated as the final value, giving you full control over the resulting list.

Prerequisite

To use this property, you must first define your available roles in the plugin configuration.

Static Roles

When you provide a static array, the roles you list are concatenated with the defaultRoles defined in your configuration.

JSON

{
  title: 'Global Settings',
  schemaType: 'settings',
  singleton: true,
  // This item will appear for 'administrator' and all default roles
  roles: ['administrator'],
}

Helpers

helpers.singleton('settings', {
  title: 'Global Settings',
  // This item will appear for 'administrator' and all default roles
  roles: ['administrator'],
});

Dynamic Roles (Callback)

Using a callback function gives you full control. Unlike the static array, the returned value of a callback is treated as the final list, meaning it does not automatically merge with defaults.

1. Exclusive Visibility

Use a callback to return a static array if you want the item to appear only for specific roles, ignoring the defaultRoles.

JSON

{
  title: 'Financial Reports',
  schemaType: 'revenue',
  // By using a callback, we ensure this ONLY appears for 'finance-admin'
  // even if other roles are set as defaults.
  roles: () => ['finance-admin'],
}

Helpers

helpers.listing('revenue', {
  title: 'Financial Reports',
  // By using a callback, we ensure this ONLY appears for 'finance-admin'
  // even if other roles are set as defaults.
  roles: () => ['finance-admin'],
});

2. Filtering Defaults

You can dynamically filter the defaultRoles based on your project's logic.

JSON

{
  title: 'Editor Dashboard',
  schemaType: 'dashboard',
  // Dynamically show for all default roles except 'viewer'
  roles: ({ defaultRoles }) => {
    return defaultRoles.filter((role) => role !== 'viewer');
  },
}

Helpers

helpers.listing('dashboard', {
  title: 'Editor Dashboard',
  // Dynamically show for all default roles except 'viewer'
  roles: ({ defaultRoles }) => {
    return defaultRoles.filter((role) => role !== 'viewer');
  },
});

3. Role Restriction based on Workspace

You can use the active workspace parameter to dynamically customize role access.

JSON

{
  title: 'Feedback',
  schemaType: 'feedback',
  // In the internal testing workspace, allow 'tester' role in addition to default roles
  roles: ({ defaultRoles, workspace }) => {
    if (workspace === 'internal-testing') {
      return [...defaultRoles, 'tester'];
    }

    return defaultRoles;
  },
}

Helpers

helpers.listing('feedback', {
  title: 'Feedback',
  // In the internal testing workspace, allow 'tester' role in addition to default roles
  roles: ({ defaultRoles, workspace }) => {
    if (workspace === 'internal-testing') {
      return [...defaultRoles, 'tester'];
    }

    return defaultRoles;
  },
});

4. Using with Workspaces

You can combine roles with the workspaces property to create multi-layered access control. This ensures an item is only visible for certain roles and only in specific workspaces.

JSON

{
  title: 'Internal Debug Tools',
  schemaType: 'debugInfo',
  // Visible only for the 'developer' role
  roles: () => ['developer'],
  // Only in the 'development-workspace'
  workspaces: () => ['development-workspace'],
}

Helpers

helpers.listing('debugInfo', {
  title: 'Internal Debug Tools',
  // Visible only for the 'developer' role
  roles: () => ['developer'],
  // Only in the 'development-workspace'
  workspaces: () => ['development-workspace'],
});

For more details on workspace-based restrictions, see the workspaces.