ArcaneButton#

A versatile button component for user interactions. Supports multiple variants, sizes, icons, and loading states.

Basic Usage#

ArcaneButton(
  label: 'Click Me',
  onPressed: () {
    print('Button clicked!');
  },
)

Properties#

Property	Type	Default	Description
`label`	`String`	required	Button text label
`onPressed`	`VoidCallback?`	`null`	Click handler. Null disables the button
`size`	`ButtonSize`	`medium`	Button size
`variant`	`ButtonVariant`	`secondary`	Visual variant
`icon`	`Component?`	`null`	Leading icon
`trailingIcon`	`Component?`	`null`	Trailing icon
`isLoading`	`bool`	`false`	Show loading spinner
`isDisabled`	`bool`	`false`	Disable the button
`fullWidth`	`bool`	`false`	Expand to full width
`href`	`String?`	`null`	If provided, renders as `<a>` tag for navigation
`showArrow`	`bool`	`false`	Show arrow indicator after label
`styles`	`ArcaneStyleData?`	`null`	Custom styling

Variants#

ArcaneButton provides named constructors for common variants:

Primary Button#

High-emphasis button for primary actions.

ArcaneButton.primary(
  label: 'Save Changes',
  onPressed: () {},
)

Secondary Button#

Medium-emphasis button for secondary actions.

ArcaneButton.secondary(
  label: 'Cancel',
  onPressed: () {},
)

Destructive Button#

For dangerous or destructive actions.

ArcaneButton.destructive(
  label: 'Delete Account',
  onPressed: () {},
)

Ghost Button#

Minimal button with no background.

ArcaneButton.ghost(
  label: 'Learn More',
  onPressed: () {},
)

Outline Button#

Bordered button with transparent background.

ArcaneButton.outline(
  label: 'View Details',
  onPressed: () {},
)

Link Button#

Text-only button styled as a link.

ArcaneButton.link(
  label: 'Terms & Conditions',
  onPressed: () {},
)

Accent Button#

Gradient background button for prominent CTAs. Uses the theme's accent gradient colors.

ArcaneButton.accent(
  label: 'Get Started',
  onPressed: () {},
)

CTA (Call-to-Action) Usage#

For CTA buttons that navigate to other pages, use the href and showArrow properties:

ArcaneButton.primary(
  label: 'View Plans',
  href: '/pricing',
  showArrow: true,
)

CTA Examples#

// Primary CTA with navigation
ArcaneButton.primary(
  label: 'Get Started',
  href: '/signup',
  showArrow: true,
  size: ButtonSize.large,
)

// Secondary CTA (outline style)
ArcaneButton.outline(
  label: 'Learn More',
  href: '/features',
  showArrow: true,
)

// Accent gradient CTA
ArcaneButton.accent(
  label: 'Start Free Trial',
  href: '/trial',
  showArrow: true,
)

// Ghost CTA (text only)
ArcaneButton.ghost(
  label: 'Contact Sales',
  href: '/contact',
)

When href is provided, the button renders as an <a> tag instead of <button>, ensuring proper navigation semantics.

Sizes#

Control button size with ButtonSize:

// Extra small
ArcaneButton(
  label: 'XS',
  size: ButtonSize.xsmall,
  onPressed: () {},
)

// Small
ArcaneButton(
  label: 'Small',
  size: ButtonSize.small,
  onPressed: () {},
)

// Medium (default)
ArcaneButton(
  label: 'Medium',
  size: ButtonSize.medium,
  onPressed: () {},
)

// Large
ArcaneButton(
  label: 'Large',
  size: ButtonSize.large,
  onPressed: () {},
)

ButtonSize Values#

Value	Description
`xsmall`	Extra small, compact
`small`	Small button
`medium`	Default size
`large`	Large button

Icons#

Add icons before or after the label:

Leading Icon#

ArcaneButton.primary(
  icon: span([text('→')]),
  label: 'Continue',
  onPressed: () {},
)

Trailing Icon#

ArcaneButton(
  label: 'Download',
  trailingIcon: span([text('↓')]),
  onPressed: () {},
)

Both Icons#

ArcaneButton(
  icon: span([text('←')]),
  label: 'Navigate',
  trailingIcon: span([text('→')]),
  onPressed: () {},
)

States#

Loading State#

Show a loading spinner:

ArcaneButton.primary(
  label: 'Saving...',
  isLoading: true,
  onPressed: () {},
)

Disabled State#

Disable interaction:

ArcaneButton(
  label: 'Disabled',
  isDisabled: true,
  onPressed: () {},
)

// Or pass null to onPressed
ArcaneButton(
  label: 'Also Disabled',
  onPressed: null,
)

Full Width#

Expand to container width:

ArcaneButton.primary(
  label: 'Full Width Button',
  fullWidth: true,
  onPressed: () {},
)

Custom Styling#

Override default styles:

ArcaneButton(
  label: 'Custom',
  styles: const ArcaneStyleData(
    borderRadius: Radius.full,
    shadow: Shadow.glowAccent,
  ),
  onPressed: () {},
)

Examples#

Form Submit Button#

ArcaneDiv(
  styles: const ArcaneStyleData(
    display: Display.flex,
    gap: Gap.md,
    justifyContent: JustifyContent.flexEnd,
  ),
  children: [
    ArcaneButton.ghost(
      label: 'Cancel',
      onPressed: () => Navigator.pop(context),
    ),
    ArcaneButton.primary(
      label: isSubmitting ? 'Saving...' : 'Save',
      isLoading: isSubmitting,
      onPressed: isSubmitting ? null : handleSubmit,
    ),
  ],
)

Button Group#

ArcaneDiv(
  styles: const ArcaneStyleData(
    display: Display.flex,
    gap: Gap.sm,
  ),
  children: [
    ArcaneButton.outline(label: 'Day', onPressed: () {}),
    ArcaneButton.primary(label: 'Week', onPressed: () {}),
    ArcaneButton.outline(label: 'Month', onPressed: () {}),
  ],
)

Destructive Action with Confirmation#

ArcaneButton.destructive(
  icon: span([text('🗑')]),
  label: 'Delete Project',
  onPressed: () {
    showConfirmDialog(
      title: 'Delete Project?',
      message: 'This action cannot be undone.',
      onConfirm: deleteProject,
    );
  },
)

Icon-Only Button#

For icon-only buttons, use ArcaneIconButton instead:

ArcaneIconButton(
  icon: span([text('×')]),
  onPressed: () {},
)

ArcaneIconButton - Icon-only buttons
ArcaneFAB - Floating action button
ArcaneToggleButton - Toggle button