abaabil.button.acc

Button Component Documentation

Overview

Button is a flexible and accessible button component built with React. It supports various configurations, including rendering as a native button or anchor element. The component is designed to be highly customizable, with support for icons, custom labels, different sizes, colors, and states (e.g., disabled, pressed).

Features:

• Customizable Appearance: Supports different sizes, colors, and full-width layout.
• Icon Support: Allows the inclusion of icons before or after the button text.
• Accessibility: Includes ARIA attributes such as aria-pressed, aria-disabled, and aria-label to ensure the button is accessible to all users.
• Flexible Rendering: Can be rendered as either a button or an a (anchor) element.

Installation

You can install the Button component using npm:

npm install abaabil.button.acc

Setup: Adding Custom Styles

To style the Button component, you need to define custom CSS variables for colors and then incorporate these variables into your Tailwind CSS configuration.

Step 1: Define Custom CSS Variables

First, add the following CSS variables to your global stylesheet, typically in your index.css or styles.css file:

:root {
  --color-primary: #3784ff;
  --color-on-primary: #ffffff;
  --color-primary-hover: #6ea3f8;
  --color-primary-focus: #1a6eff;
  --color-primary-active: #0056e0;
  --color-primary-disabled: #b0b0b0;
  --color-on-primary-disabled: #ffffff;
}

These variables define the color scheme used by the Button component for its various states (default, hover, focus, active, and disabled).

Step 2: Extend Tailwind CSS Configuration

Next, extend the Tailwind CSS configuration to utilize these custom variables. Add the following to your tailwind.config.js file:

module.exports = {
  theme: {
    extend: {
      colors: {
        primary: 'var(--color-primary)',
        'on-primary': 'var(--color-on-primary)',
        'primary-hover': 'var(--color-primary-hover)',
        'primary-focus': 'var(--color-primary-focus)',
        'primary-active': 'var(--color-primary-active)',
        'primary-disabled': 'var(--color-primary-disabled)',
        'on-primary-disabled': 'var(--color-on-primary-disabled)',
      },
    },
  },
}

This setup ensures that Tailwind's utility classes for colors reference your custom variables, allowing for consistent theming across your application.

Props

as

• Type: string
• Default: 'button'
• Options: 'button', 'a'
• Description: Specifies the HTML element that the component will render. If set to 'button', it will render as a native <button> element. If set to 'a', it will render as an anchor <a> element.

icon

• Type: string
• Description: The ID of the icon to be displayed before the button's text. If provided, the Icon component will render this icon.

children

• Type: node
• Description: The content or text to be displayed inside the button. This is the primary label of the button.

actionIcon

• Type: string
• Description: The ID of the icon to be displayed after the button's text, typically used for indicating an action.

className

• Type: string
• Description: Additional CSS classes to apply to the button for custom styling.

color

• Type: string
• Description: Specifies the color theme of the button. If not provided, default colors will be applied based on the disabled state.

size

• Type: string
• Options: 'sm', 'lg', undefined
• Description: Defines the size of the button. If not specified, the button will use default size styles.

disabled

• Type: boolean
• Default: false
• Description: When true, the button is disabled and cannot be interacted with. This prop also sets the aria-disabled attribute for accessibility.

isPressed

• Type: boolean
• Description: When true, the button is in a pressed or toggled state. This prop sets the aria-pressed attribute for accessibility. Should be used for buttons that function as toggles.

fullWidth

• Type: boolean
• Default: false
• Description: When true, the button will take up the full width of its container.

aria-label

• Type: string
• Description: Provides an accessible label for the button, especially important when the button includes an icon but no visible text.

ref

• Type: React.Ref
• Description: A ref to access the underlying DOM element.

props

• Type: object
• Description: Additional props will be spread onto the rendered element.

Accessibility Considerations

• Icon-only Buttons: When an icon is used without accompanying text (children), the aria-label prop must be provided. This ensures that screen readers can announce the purpose of the button.

• aria-pressed: The aria-pressed attribute is conditionally applied only when isPressed is explicitly set. This is particularly important for toggle buttons to communicate their state to assistive technologies.

• Keyboard Navigation: The component ensures proper keyboard navigation by setting the correct element type or role and ensuring focus styles are visible.

Example Usage

Basic Button

<Button>
  Click Me
</Button>

Button with Icon

<Button icon="plus">
  Add Item
</Button>

Icon-only Button

<Button icon="settings" aria-label="Settings" />

Toggle Button

<Button isPressed={true}>
  Toggle On
</Button>

Full-Width Button

<Button fullWidth>
  Full Width Button
</Button>

Anchor Button

<Button as="a" href="https://example.com">
  Visit Example
</Button>

Best Practices

1. Always provide an aria-label for icon-only buttons to ensure that the button’s purpose is clear to screen reader users.
2. Use isPressed for toggle buttons to clearly communicate the button's state to all users.
3. Test the component with various screen readers and keyboard navigation tools to ensure accessibility across different platforms and devices.