Fluxon.Components.Button (Fluxon v2.0.0)

A versatile button component that provides consistent, accessible, and visually appealing interactive elements.

This component offers a comprehensive solution for building interactive elements across your application, from simple actions to complex workflows. It seamlessly integrates with Phoenix LiveView and automatically renders either a <button> or an <a> tag based on the provided attributes, making it suitable for navigation, form submissions, and general user interactions.

Usage

Buttons can be used in their simplest form for actions and interactions:

<.button>Outline Button (Default)</.button>
<.button variant="solid" color="primary">Solid Button</.button>
<.button variant="soft" color="primary">Soft Button</.button>
<.button variant="ghost">Ghost Button</.button>

Visual Variants

The component supports six distinct visual styles:

<.button variant="solid" color="primary">Solid</.button>
<.button variant="soft" color="primary">Soft</.button>
<.button variant="surface" color="primary">Surface</.button>
<.button variant="outline">Outline (Default)</.button>
<.button variant="dashed">Dashed</.button>
<.button variant="ghost">Ghost</.button>

Each variant is designed for specific use cases:

solid: Filled button with strongest visual weight, perfect for primary actions
soft: Subtle background without border, ideal for secondary actions
surface: Like soft but with a border, great for contained secondary actions
outline: Button with border and transparent background, good for alternative actions (Default)
dashed: Similar to outline but with dashed border, useful for placeholder or draft actions
ghost: Borderless button with hover state, great for minimal actions

Colors and Theming

The button supports multiple semantic color schemes, each carefully designed for both light and dark modes:

<.button color="primary" variant="solid">Primary</.button>
<.button color="info" variant="soft">Info</.button>
<.button color="success" variant="surface">Success</.button>
<.button color="warning" variant="outline">Warning</.button>
<.button color="danger" variant="ghost">Danger</.button>

Available colors and their common use cases:

primary: Most important actions (e.g., save, submit, continue)
info: Informational actions (e.g., view details, learn more)
success: Positive actions (e.g., confirm, approve)
warning: Actions that require attention (e.g., confirmation prompts)
danger: Destructive actions (e.g., delete, remove)

Each color includes specific styling for all variants:

solid: Full color with contrasting foreground text
soft: Subtle color background with colored text
surface: Soft background with matching border and colored text
outline: Colored border and text with transparent background
dashed: Colored dashed border and text with transparent background
ghost: Colored text with transparent background

Size Options

The component offers various size variants to accommodate different UI needs:

<.button size="xs">Extra Small</.button>
<.button size="sm">Small</.button>
<.button size="md">Medium (Default)</.button>
<.button size="lg">Large</.button>
<.button size="xl">Extra Large</.button>

Standard Sizes

Size	Height	Text	Icon Size	Use Case
`xs`	28px	xs	14px	Compact UI elements
`sm`	32px	sm	16px	Secondary actions
`md`	36px	sm	20px	Default size
`lg`	40px	base	20px	Primary actions
`xl`	44px	base	20px	Hero sections, prominent calls to action

Icon-Only Sizes

Dedicated sizes are available for icon-only buttons, ensuring they are square and the icon is centered:

<.button size="icon-sm">
  <.icon name="hero-pencil" class="icon" />
</.button>
<.button size="icon" variant="solid" color="primary">
  <.icon name="hero-magnifying-glass" class="icon" />
</.button>
<.button size="icon-lg" variant="ghost">
  <.icon name="hero-x-mark" class="icon" />
</.button>

Size	Dimensions	Icon Size	Use Case
`icon-xs`	28px x 28px	14px	Very compact icon actions
`icon-sm`	32px x 32px	16px	Small icon actions
`icon-md`	36px x 36px	20px	Standard icon actions (Default icon size)
`icon`	36px x 36px	20px	Standard icon actions (Default icon size)
`icon-lg`	40px x 40px	18px (special case)	Large icon actions
`icon-xl`	44px x 44px	20px	Extra large icon actions

Working with Icons

The button component automatically handles icon sizing and spacing based on the chosen size. Place an icon component from Fluxon.Components.Icon directly inside the button's slot.

<.button size="lg" variant="solid" color="success">
  <.icon name="hero-check-circle" class="icon" /> Order Confirmed
</.button>

<.button size="sm" variant="ghost" color="danger">
  <.icon name="hero-trash" class="icon" /> Remove Item
</.button>

<.button size="icon" phx-click="toggle-sidebar">
  <.icon name="hero-bars-3" class="icon" />
</.button>

Icon Class Required

Remember to add the icon class to your <.icon> component for correct sizing and alignment:

<.button>
  <.icon name="hero-check" class="icon" /> <!-- Correct -->
</.button>

The icon class ensures the icon scales appropriately with the button's size attribute.

Automatic Link Rendering

The component intelligently renders either a <button> element or an anchor (<a>) tag based on the attributes provided. If you include href, navigate, or patch, it will automatically render as a link. Otherwise, it defaults to a button.

<.button navigate={~p"/dashboard"} variant="solid" color="primary">
  Go to Dashboard
</.button>

<.button href="https://example.com" target="_blank" variant="soft">
  External Link
</.button>

<.button patch={~p"/users?sort=name"} variant="ghost">
  Sort by Name
</.button>

When rendered as a link, it supports all standard anchor attributes (target, rel, etc.) and Phoenix LiveView link attributes (navigate, patch, replace, method, csrf_token).

When rendered as a button, it supports standard button attributes (type, disabled, form, phx-click, etc.).

Real-World Examples

Primary Action

<.button variant="solid" color="primary" size="lg" phx-click="submit-form">
  <.icon name="hero-paper-airplane" class="icon" />
  Submit Application
</.button>

Danger Action

<.button variant="solid" color="danger" phx-click="delete_item" phx-value-id={@item.id} phx-confirm="Are you sure?">
  <.icon name="hero-trash" class="icon" />
  Delete Item
</.button>

Navigation Link

<.button navigate={~p"/settings"} variant="ghost" size="sm">
  <.icon name="hero-cog-6-tooth" class="icon" />
  Account Settings
</.button>

Icon-Only Action

<.button size="icon" variant="ghost" phx-click="show-details" phx-value-id={@user.id} aria-label="View user details">
  <.icon name="hero-eye" class="icon" />
</.button>

Summary

Components

button(assigns)

Renders a button or link with customizable styles and attributes.

button_group(assigns)

Renders a container to visually group multiple buttons.

Components

button(assigns)

Renders a button or link with customizable styles and attributes.

This component provides a flexible way to create interactive elements with consistent styling across your application. It supports various sizes, colors, and visual variants while maintaining proper accessibility and user experience standards.

Attributes

color (:string) - The semantic color scheme of the button. Each color includes specific styles for all variants and maintains proper contrast in both light and dark modes. Available options: primary, danger, warning, success, info.
Defaults to "primary".
size (:string) - The size variant of the button. Affects height, padding, font size, and icon sizing. Defaults to "md".
variant (:string) - The visual style variant of the button:
- solid: Filled button with strongest visual weight (primary actions).
- soft: Subtle background without border (secondary actions).
- surface: Like soft but with border (contained secondary actions).
- outline: Border with transparent background (alternative actions, default).
- dashed: Dashed border with transparent background (placeholder/draft actions).
- ghost: No border or background, minimal styling (utility actions).
Defaults to "outline".
disabled (:boolean) - Whether the button is disabled. When true, the button becomes non-interactive. Defaults to false.
class (:any) - Additional CSS classes to be applied to the button. These are merged with the component's base classes, variant styles, and size styles.
Defaults to nil.
Global attributes are accepted. Additional HTML attributes to apply to the underlying <button> or <a> element. The component automatically determines whether to render a button or an anchor based on the presence of href, navigate, or patch attributes. It supports attributes relevant to both element types. Supports all globals plus: ["target", "download", "rel", "hreflang", "type", "referrerpolicy", "navigate", "patch", "href", "replace", "method", "csrf_token", "autofocus", "disabled", "form", "formaction", "formenctype", "formmethod", "formnovalidate", "formtarget", "name", "type", "value"].

Slots

inner_block (required) - The content to be displayed within the button. Supports text and icons with automatic spacing and sizing based on the selected size variant.

button_group(assigns)

Renders a container to visually group multiple buttons.

This component wraps multiple <.button> components, styling them to appear as a single, connected unit.

Examples

<.button_group>
  <.button>Year</.button>
  <.button>Month</.button>
  <.button>Week</.button>
</.button_group>

<.button_group>
  <.button variant="solid" color="info">Copy</.button>
  <.button variant="solid" color="info" size="icon-md" title="Copy details">
    <.icon name="hero-clipboard-document" class="icon" />
  </.button>
</.button_group>

Attributes

class (:any) - Additional CSS classes for the group container. Defaults to nil.
Global attributes are accepted. Additional HTML attributes for the group container.

Slots

inner_block (required) - The slot for the buttons to be grouped.