Browse docs

Button

Standard Material-UI button with an additional access prop for role-based access control. When the current user lacks the required permission, the button is automatically hidden or disabled.

Examples

Contained

<Button variant="contained">Submit</Button>

Outlined

<Button variant="outlined">Cancel</Button>

Text

<Button variant="text">Learn more</Button>

Disabled

<Button variant="contained" disabled>Disabled</Button>

Sizes

<Stack direction="row" spacing={2} alignItems="center">
  <Button size="small" variant="contained">Small</Button>
  <Button size="medium" variant="contained">Medium</Button>
  <Button size="large" variant="contained">Large</Button>
</Stack>

Quick Start

tsx

import { Button } from '@dashforge/ui';

// Basic usage
<Button variant="contained" onClick={handleSubmit}>Submit</Button>

// With RBAC — hidden if user lacks 'invoices:delete' permission
<Button
  variant="contained"
  color="error"
  access={{ permission: 'invoices:delete' }}
  onClick={handleDelete}
>
  Delete Invoice
</Button>

API

Prop	Type	Default	Description
`variant`	`'text' \| 'outlined' \| 'contained'`	`'text'`	Visual style of the button.
`color`	`'primary' \| 'secondary' \| 'error' \| 'warning' \| 'info' \| 'success'`	`'primary'`	Color theme.
`size`	`'small' \| 'medium' \| 'large'`	`'medium'`	Button size.
`disabled`	`boolean`	`false`	Disables the button.
`fullWidth`	`boolean`	`false`	Stretches to fill container width.
`type`	`'button' \| 'submit' \| 'reset'`	`'button'`	HTML button type.
`onClick`	`() => void`	—	Click handler.
`startIcon`	`ReactNode`	—	Icon rendered before the label.
`endIcon`	`ReactNode`	—	Icon rendered after the label.
`href`	`string`	—	Renders the button as an anchor tag.
`access`	`AccessRequirement`	—	RBAC permission requirement. Button is hidden when access is denied.

Notes

The access prop integrates with the DashForge RBAC system. Provide { permission: 'resource:action' } to gate visibility on a specific permission.
When rendered as a link (href), all RBAC rules still apply.

Capabilities

Full MUI Button API

All MUI Button props are supported: variant, color, size, startIcon, endIcon, fullWidth, and more. Button is a thin wrapper that preserves the complete MUI ergonomics.

Built-in RBAC Support

Declarative access control via the access prop. No need for scattered useCan() checks in userland. Hide, disable, or fallback to disabled based on user permissions.

Action Authorization

Perfect for controlling primary actions (Save, Submit), destructive operations (Delete, Archive), publishing workflows (Publish, Approve), and contextual actions (Edit, Duplicate).

Explicit Readonly Fallback

Buttons are action components without readonly semantics. When onUnauthorized: "readonly" is used, the button explicitly falls back to disabled state for safe, predictable behavior.

OR Logic for Disabled State

Combines explicit disabled prop with RBAC access state. Button is disabled if either source requires it, allowing you to mix authorization with loading states and validation.

Zero Dependencies on Form System

Button does not depend on DashFormContext, react-hook-form, or @dashforge/forms. It only depends on @dashforge/rbac for access control, making it universally usable.