All components (244)

Permission gate

Management · PermissionGate

What it is and when to use it

Shows, hides or switches off a piece of interface depending on what whoever uses it has been granted: the delete button only for whoever can delete, the settings tab only for administration.

When to use it

A button, a menu or a section that not every user should see or be able to use.
PermissionProvider goes once, at the top of the application, with granted: a list (['invoices.read', 'customers.*']) or a function with your own policy. usePermission and usePermissions give the same answer in code, for a shortcut or a menu.
permission is one permission or a list; with several, match="all" (default) needs all of them and match="any" needs only one. group.* grants everything under group and *, everything.
mode="hide" (default) paints nothing, or paints fallback. mode="disable" paints the content switched off and says why (reason).
While the permissions load (loading on the provider), the gate does not decide: it shows loadingFallback, so a button does not flash and then disappear.

When not to

As the only protection: hiding something on screen does not protect it. Every action is also checked on the server.
For the user to choose permissions: PermissionMatrix.

Keyboard: it adds nothing. When switched off, the content leaves the tab order because the browser disables every control.

Accessibility: switching off is a real <fieldset disabled>: the browser disables every button, field and checkbox inside on its own, and the reason is read as the group's description. With permission it adds nothing to the DOM. Without a provider it grants nothing and says so in the console, so forgetting it shows.

Fine appearance: no variables of its own; what is switched off lowers its opacity (amset-permission).

What it looks like

You need the permission to delete orders.

You don't have access to the invoices.

// Dentro del proveedor de permisos de la aplicación
<>
  <PermissionGate permission="pedidos.borrar" mode="disable" reason="You need the permission to delete orders.">
    <Button tone="error">Delete order</Button>
  </PermissionGate>
  <PermissionGate permission="facturas.ver" fallback={<p>You don't have access to the invoices.</p>}>
    <Facturas />
  </PermissionGate>
</>

Props

Import it with import { PermissionGate } from '@amset/ui'. Required props are marked.

Prop	Type	What it does
`children`required	`ReactNode`	—
`permission`required	`string \| readonly string[]`	The permission that is needed, or the list of them. With none, the gate opens.
`fallback`	`ReactNode`	What is shown instead of the content when it is hidden.
`loadingFallback`	`ReactNode`	What is shown while the permissions load. By default, nothing.
`match`	`PermissionMatch`	With several permissions: `all` (default) needs all of them and `any` needs only one.
`mode`	`"hide" \| "disable"`	What happens without permission. `hide` (default) paints nothing, or paints `fallback`. `disable` paints the content but switched off: every control inside is disabled and the reason is read.
`reason`	`string`	With `disable`: why it is switched off, which is read along with the content.

In the test bench

Every state and variant, to try one at a time, on its page at ui.amset.tech: