RoleGate

Conditional rendering component that shows or hides content based on user roles. It supports OR logic (user needs any role) or AND logic (user needs all roles). 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: Use ‘owner’ for app creator, ‘authenticated’ for any logged‑in user.

Tip: Use custom role names like ‘editor’, ‘viewer’, ‘manager’ as needed.

Tip: Default behavior is OR logic – 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.

Tip: Use true only when user must have multiple specific roles simultaneously.

showLoginPrompt

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

Tip: Use true (default) to guide users to login.

Tip: 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'}]