@fiscozen/button

A comprehensive button component library for Vue 3 applications, featuring multiple variants, sizes, and icon support.

Features

• Multiple Variants: Primary, Secondary, Invisible, Danger, and Success styles
• Environment-Based Sizing: Two environment options (backoffice, frontoffice) for different use cases
• Icon Support: Built-in icon integration with customizable positioning
• Accessibility: Full keyboard navigation and ARIA support
• Customizable: Flexible styling with container class overrides
• TypeScript: Full type safety with TypeScript definitions
• Semantic Colors: Uses design system tokens for consistent theming

Installation

npm install @fiscozen/button

Components

This package exports three components:

• FzButton - Standard button with label and optional icon
• FzIconButton - Icon-only button for compact interfaces
• FzButtonGroup - Container for grouping related buttons

Basic Usage

FzButton

<script setup lang="ts">
import { FzButton } from '@fiscozen/button'
</script>

<template>
  <FzButton label="Click me" />
</template>

With Variants

<template>
  <!-- Primary (default) -->
  <FzButton variant="primary" label="Primary Action" />
  
  <!-- Secondary -->
  <FzButton variant="secondary" label="Secondary Action" />
  
  <!-- Invisible -->
  <FzButton variant="invisible" label="Subtle Action" />
  
  <!-- Danger -->
  <FzButton variant="danger" label="Delete" />
  
  <!-- Success -->
  <FzButton variant="success" label="Confirm" />
</template>

With Icons

<template>
  <!-- Icon before label (default) -->
  <FzButton 
    label="Save" 
    iconName="save" 
    iconPosition="before" 
  />
  
  <!-- Icon after label -->
  <FzButton 
    label="Next" 
    iconName="arrow-right" 
    iconPosition="after" 
  />
  
  <!-- Custom icon variant -->
  <FzButton 
    label="Settings" 
    iconName="gear" 
    iconVariant="fas" 
  />
</template>

Environment (Size)

<template>
  <!-- Frontoffice environment (default) -->
  <FzButton environment="frontoffice" label="Frontoffice Button" />
  
  <!-- Backoffice environment -->
  <FzButton environment="backoffice" label="Backoffice Button" />
</template>

Size Prop (Deprecated)

The size prop is deprecated but still functional for backward compatibility. Use environment instead:

<template>
  <FzButton size="lg" label="Legacy Large" />
</template>

Disabled State

<template>
  <FzButton label="Disabled Button" :disabled="true" />
</template>

Using Slots

<template>
  <!-- Default slot (overrides label prop) -->
  <FzButton>
    <span>Custom <strong>HTML</strong> Content</span>
  </FzButton>
  
  <!-- Custom icon slots -->
  <FzButton label="Custom Icon">
    <template #before>
      <CustomIcon />
    </template>
  </FzButton>
  
  <FzButton label="Custom Icon After">
    <template #after>
      <CustomIcon />
    </template>
  </FzButton>
</template>

Props

FzButton Props

Slots

Behavior & Concepts

Label vs Slot Priority

When both label prop and default slot are provided, the slot takes precedence:

<FzButton label="This won't show">
  This will show instead
</FzButton>

Icon Display Logic

Icons are only displayed when both label (or default slot) and iconName are provided. This ensures proper spacing and layout.

Container Class Customization

By default, the label container has the truncate class to handle text overflow. You can:

1. Add classes (default behavior):

<FzButton label="Text" containerClass="font-bold" />
<!-- Results in: class="truncate font-bold" -->

2. Override completely:

<FzButton 
  label="Text" 
  containerClass="custom-class" 
  :overrideContainerClass="true" 
/>
<!-- Results in: class="custom-class" (no truncate) -->

Examples

Form Actions

<template>
  <div class="flex gap-12">
    <FzButton 
      variant="primary" 
      label="Submit" 
      @click="handleSubmit"
    />
    <FzButton 
      variant="secondary" 
      label="Cancel" 
      @click="handleCancel"
    />
  </div>
</template>

Destructive Action with Confirmation

<template>
  <FzButton 
    variant="danger" 
    label="Delete Account" 
    iconName="trash"
    :disabled="!confirmed"
    @click="handleDelete"
  />
</template>

Navigation with Icons

<template>
  <div class="flex gap-8">
    <FzButton 
      variant="secondary" 
      label="Back" 
      iconName="arrow-left" 
      iconPosition="before"
      environment="backoffice"
    />
    <FzButton 
      variant="primary" 
      label="Continue" 
      iconName="arrow-right" 
      iconPosition="after"
      environment="backoffice"
    />
  </div>
</template>

Loading State (Custom Implementation)

<script setup lang="ts">
import { ref } from 'vue'
import { FzButton } from '@fiscozen/button'

const isLoading = ref(false)

async function handleAction() {
  isLoading.value = true
  try {
    await performAction()
  } finally {
    isLoading.value = false
  }
}
</script>

<template>
  <FzButton 
    :disabled="isLoading"
    @click="handleAction"
  >
    <span v-if="isLoading">Loading...</span>
    <span v-else>Submit</span>
  </FzButton>
</template>

Accessibility

FzButton follows WCAG 2.1 AA standards and includes:

• Semantic HTML: Renders as a native <button> element with type="button"
• Keyboard Navigation: Full support for Enter and Space keys
• ARIA Attributes:
  • aria-disabled is always present with explicit "true" or "false" values (Vue 3 compatible)
• Disabled State: Properly prevents click events and visual feedback when disabled
• Screen Reader Compatible: Works with NVDA, JAWS, and VoiceOver
• Focus Indicators: Visible focus states with 3:1 contrast ratio (blue border)
• Color Contrast: All variants meet 4.5:1 contrast ratio for text

Notes

Environment vs Size

The button supports two environments that determine sizing:

• backoffice: Compact button for internal applications
• frontoffice: Larger button for customer-facing interfaces (default)

The deprecated size prop maps to environments as follows:

• xs, sm, md → maps to backoffice
• lg → maps to frontoffice

Variant Selection

The variant attribute is used instead of type to avoid confusion with the HTML type attribute on button elements.

FzButtonGroup

Container for grouping buttons in a horizontal layout with fixed spacing. Uses FzContainer component internally to display buttons in a row with consistent gap between them. Buttons maintain fixed widths (50% for 2 buttons, 33.333% for 3 buttons) regardless of content, with text truncation handled by FzButton component. Component occupies 100% width of its container.

Features

• Horizontal layout only
• Fixed gap spacing
• Fixed button widths: 50% for 2 buttons, 33.333% for 3 buttons
• Text truncation handled automatically by FzButton component
• No wrapping - buttons stay on a single row
• 100% width of container
• No props required

Basic Usage

<script setup>
import { FzButtonGroup, FzButton } from '@fiscozen/button'
</script>

<template>
  <FzButtonGroup>
    <FzButton variant="primary">Save</FzButton>
    <FzButton variant="secondary">Cancel</FzButton>
    <FzButton variant="secondary">Delete</FzButton>
  </FzButtonGroup>
</template>

FzButtonGroup Props

No props required. The component always displays buttons horizontally with a fixed 16px gap.

Deprecated Props:

The following props are deprecated and will be removed in a future version. They are maintained for backward compatibility but have no effect:

• horizontal - Component is always horizontal. This prop will be ignored.
• gap - Component always uses fixed gap spacing. This prop will be ignored.
• size - Component always uses fixed gap size. This prop will be ignored.

A runtime warning will be displayed when these props are used. Please remove them from your code.

FzButtonGroup Examples

Action Buttons Group

<template>
  <FzButtonGroup>
    <FzButton variant="primary">Primary Action</FzButton>
    <FzButton variant="secondary">Secondary Action</FzButton>
    <FzButton variant="invisible">Cancel</FzButton>
  </FzButtonGroup>
</template>

Two Buttons (Frontoffice)

<template>
  <FzButtonGroup>
    <FzButton variant="primary" environment="frontoffice">Save</FzButton>
    <FzButton variant="secondary" environment="frontoffice">Cancel</FzButton>
  </FzButtonGroup>
</template>

Two Buttons (Backoffice)

<template>
  <FzButtonGroup>
    <FzButton variant="primary" environment="backoffice">Save</FzButton>
    <FzButton variant="secondary" environment="backoffice">Cancel</FzButton>
  </FzButtonGroup>
</template>

Three Buttons (Frontoffice)

<template>
  <FzButtonGroup>
    <FzButton variant="primary" environment="frontoffice">Save</FzButton>
    <FzButton variant="secondary" environment="frontoffice">Cancel</FzButton>
    <FzButton variant="secondary" environment="frontoffice">Delete</FzButton>
  </FzButtonGroup>
</template>

Three Buttons (Backoffice)

<template>
  <FzButtonGroup>
    <FzButton variant="primary" environment="backoffice">Save</FzButton>
    <FzButton variant="secondary" environment="backoffice">Cancel</FzButton>
    <FzButton variant="secondary" environment="backoffice">Delete</FzButton>
  </FzButtonGroup>
</template>

FzButtonGroup Behavior

• Fixed Width Layout: Buttons maintain fixed widths based on the number of buttons:
  • 2 buttons: Each button occupies 50% of the container width
  • 3 buttons: Each button occupies 33.333% of the container width
• Text Truncation: Long button text is automatically truncated with ellipsis (...) by the FzButton component
• No Configuration Needed: The component automatically detects the number of buttons and applies the appropriate sizing

FzButtonGroup Accessibility

The component preserves accessibility attributes of button children:

• Keyboard navigation works correctly
• ARIA labels and descriptions are maintained
• Disabled states are preserved
• Screen readers can navigate through buttons normally

The component itself is a semantic div container and does not interfere with button accessibility.

FzIconButton

Icon-only button component with notification badge support. Ideal for compact interfaces and toolbars where space is limited.

Features

• Icon-only design for compact interfaces
• Multiple variants (primary, secondary, invisible, danger)
• Two environments (backoffice, frontoffice)
• Compact mode: 20×20 control with a 44×44 touch area
• Notification badge overlay support
• Customizable icon variant
• Full accessibility support
• TypeScript support

Basic Usage

<template>
  <FzIconButton iconName="bell" ariaLabel="Notifications" />
</template>

Variants

<template>
  <div class="flex gap-8">
    <FzIconButton iconName="bell" variant="primary" ariaLabel="Notifications" />
    <FzIconButton iconName="settings" variant="secondary" ariaLabel="Settings" />
    <FzIconButton iconName="trash" variant="invisible" ariaLabel="Delete" />
    <FzIconButton iconName="trash" variant="danger" ariaLabel="Delete" />
  </div>
</template>

Environments

<template>
  <div class="flex gap-8 items-center">
    <FzIconButton 
      iconName="settings" 
      environment="backoffice" 
      ariaLabel="Settings (backoffice)" 
    />
    <FzIconButton 
      iconName="settings" 
      environment="frontoffice" 
      ariaLabel="Settings (frontoffice)" 
    />
  </div>
</template>

With Notification Badge

<template>
  <FzIconButton 
    iconName="bell" 
    hasNotification 
    ariaLabel="Notifications with badge"
  />
</template>

Compact

compact draws a 20×20 box with a 12px glyph, for a control laid over something small, such as the remove X on an image preview. The clickable area still extends to 44×44 (the minimum touch target) past the visible edge, without taking layout space: the component measures 20×20.

<template>
  <FzIconButton
    compact
    variant="secondary"
    iconName="xmark"
    ariaLabel="Rimuovi allegato"
    @click="remove"
  />
</template>

The touch area overflows the box by 12px on every side, so where you place the box decides whether it stays whole:

• Keep the box at least 12px from the edge of any container that clips overflow: the image it sits on, a horizontally scrolling strip. Closer than that, the clipped part of the touch area stops responding. For a 20px box in the corner of an image, that means 12px from the top and 12px from the right.
• Keep two compact buttons at least 24px apart (edge to edge), or their touch areas overlap and a tap between them hits whichever comes later in the DOM.

Compact mode needs a background to stay readable over an image, so invisible renders as secondary and logs a warning. environment has no effect while compact is on.

With Tooltip (Recommended)

<template>
  <FzTooltip content="Notifications">
    <FzIconButton iconName="bell" ariaLabel="Notifications" />
  </FzTooltip>
</template>

FzIconButton Props

FzIconButton Behavior & Concepts

Notification Badge

The notification badge appears as a circular indicator in the top-right corner when hasNotification is true.

FzIconButton Accessibility

FzIconButton follows WCAG 2.1 AA standards and includes:

• ARIA Labels: Icon buttons require explicit labels for screen readers. Use ariaLabel prop or wrap with FzTooltip for accessible labels
• Keyboard Navigation: Full support for Enter and Space keys
• Disabled State: Properly prevents click events and visual feedback when disabled
• Screen Reader Compatible: Works with NVDA, JAWS, and VoiceOver
• Focus Indicators: In compact mode a 2px ring is drawn inside the 20px box, against the button's own fill: white on primary (4.11:1) and danger (3.77:1), blue-600 on secondary (5.93:1). At the larger sizes focus darkens the border, which stays below 3:1 against the fill on primary (1.44:1) and danger (1.76:1)
• Touch Target: Compact mode keeps a 44×44 clickable area around the 20×20 box
• Notification Badge: Marked as aria-hidden="true" to prevent screen reader announcements

FzIconButton Examples

Toolbar Actions

<template>
  <div class="flex gap-4">
    <FzTooltip content="Notifications">
      <FzIconButton iconName="bell" hasNotification ariaLabel="Notifications" />
    </FzTooltip>
    <FzTooltip content="Settings">
      <FzIconButton iconName="settings" variant="secondary" ariaLabel="Settings" />
    </FzTooltip>
    <FzTooltip content="Help">
      <FzIconButton iconName="question" variant="invisible" ariaLabel="Help" />
    </FzTooltip>
  </div>
</template>

Form Actions

<template>
  <div class="flex gap-4">
    <FzIconButton 
      iconName="save" 
      variant="primary" 
      ariaLabel="Save"
      @click="handleSave"
    />
    <FzIconButton 
      iconName="trash" 
      variant="secondary" 
      ariaLabel="Delete"
      :disabled="!canDelete"
      @click="handleDelete"
    />
  </div>
</template>

Related Components

• FzIconButton: Use for icon-only buttons without labels
• FzButtonGroup: Use to group related buttons with consistent spacing