RoleGate

Conditional rendering component that shows or hides content based on user roles. It supports OR logic (any role matches) or AND logic (all roles must match). Use it for role‑specific UI elements such as admin buttons or owner‑only sections.

Use Cases

• Show admin‑only buttons to users with ‘owner’ or ‘admin’ role
• Display editor tools only to users with ‘editor’ role
• Hide sensitive actions from non‑owners
• Create role‑specific UI sections

Properties

allowedRoles

List of role names that can view the content. User needs ANY role (OR logic) or ALL roles (AND logic) depending on requireAllRoles setting. Type: array.

Tip: System roles – use ‘owner’ for app creator, ‘authenticated’ for any logged‑in user.
Custom roles – use names like ‘editor’, ‘viewer’, ‘manager’ as needed.
OR logic – default behavior; user needs ANY of these roles (most common).

requireAllRoles

If true, user must have ALL roles in allowedRoles. If false (default), user needs ANY role (OR logic). Type: boolean. Default: false.

Tip: Use false (default) for most cases – user needs ANY role.
Use true only when the user must possess multiple specific roles simultaneously.

showLoginPrompt

If true, shows a login prompt to unauthenticated users. If false, shows nothing. Type: boolean. Default: true.

Tip: Use true (default) to guide users to log in.
Use false when content should silently disappear for unauthorized users.

items

Array of Puck components to conditionally render based on roles. Each item is a full component object with type and props. Type: array.

Best Practices

• Use OR logic (requireAllRoles: false) by default – user needs ANY of the allowed roles
• Use AND logic (requireAllRoles: true) only when user must have ALL specified roles
• Set showLoginPrompt: true to guide unauthenticated users
• Wrap buttons, sections, or entire components in RoleGate
• Use items array to nest multiple components

Common Mistakes

Using requireAllRoles: true when OR logic is intended

Why it's a problem: User must have ALL roles (admin AND editor) instead of ANY role. Most cases need OR logic.

Fix: Use requireAllRoles: false (default) for OR logic – user needs ANY allowed role.

Empty allowedRoles array

Why it's a problem: No roles allowed means content never shows, even to owner.

Fix: Specify at least one role in allowedRoles (e.g., ['owner']).

Using items as simple objects instead of Puck components

Why it's a problem: Items must be full component objects with type and props.

Fix: Use format: [{type: 'Button', props: {...}}] not just [{label: 'Click'}].