# Button
Buttons make actions apparent to users and can navigate to different pages or perform actions. They can display text, icons, or both.

## Overview
Button supports four variants that change its visual style, each applied as an attribute:

| Attribute | Description |
| --------- | ----------- |
| `daff-button` | Rectangular button with background color |
| `daff-flat-button`| Rectangular button with no outline or background color |
| `daff-icon-button` | Icon only button used with icon fonts |
| `daff-stroked-button` | Rectangular button with outline, no background color |

Native `<button>` or `<a>` elements should always be used in order to provide an easy, accessible experience for users.

- Use `<a>` for navigation to new pages or different sections.
- Use `<button>` for actions performed within the same page.

<daff-docs-example-viewer example="button-types"></daff-docs-example-viewer>

## Usage

Import the button type you need into your component:

Available imports:
- `DAFF_BASIC_BUTTON_COMPONENTS`
- `DAFF_FLAT_BUTTON_COMPONENTS`
- `DAFF_ICON_BUTTON_COMPONENTS`
- `DAFF_STROKED_BUTTON_COMPONENTS`
- `DAFF_BUTTON_COMPONENTS` (all types)

```ts
import { DAFF_BASIC_BUTTON_COMPONENTS } from '@daffodil/design/button';

@Component({
  selector: 'custom-component',
  templateUrl: './custom-component.component.html',
  imports: [
    DAFF_BASIC_BUTTON_COMPONENTS,
  ],
})
export class CustomComponent {}
```

> **Deprecation notice:**
> 
> `DaffButtonModule` is deprecated. Use the standalone component imports instead.

## Anatomy
A button is composed of a label with optional icons:

```html
<button daff-button>
  <fa-icon daffPrefix></fa-icon>
  Add to cart
</button>
```

- The label describing the action. Always provide one unless the button uses an icon that is universally understood and accessible.
- Add the `daffPrefix` or `daffSuffix` directive to an icon to place it before or after the label text. Avoid using both at once.

## Features

### Icons
Render an icon on either side of the button label with the `daffPrefix` and `daffSuffix` directives.

<daff-docs-example-viewer example="button-with-icon"></daff-docs-example-viewer>

### Colors
Use the `color` property to change the color of a button.

> Note: `dark`, `light`, and `theme` should be used on appropriate backgrounds for sufficient contrast.

<daff-docs-example-viewer example="button-colors"></daff-docs-example-viewer>

### Elevation
Add shadows to buttons with the `elevated` property.

> Note: The `elevated` property is not supported for flat, icon, and underline buttons.

<daff-docs-example-viewer example="elevated-button"></daff-docs-example-viewer>

### Sizes
Use the `size` property to control button dimensions. The default size is `md`.

<daff-docs-example-viewer example="button-sizes"></daff-docs-example-viewer>

### Status indicators
Status indicators help users understand the type of action a button performs and its importance relative to other buttons in the same context. Use the `status` property to convey different semantic meanings.

<daff-docs-example-viewer example="statusable-button"></daff-docs-example-viewer>

### Disabled
Use the `disabled` property to disable a button that shouldn't be actionable. The button will appear faded and won't respond to user interaction.

<daff-docs-example-viewer example="disabled-button"></daff-docs-example-viewer>

### Loading
Use the `loading` property to indicate that an action is being processed. When `loading` is set to `true`, the button displays a spinner.

<daff-docs-example-viewer example="loading-button"></daff-docs-example-viewer>

## Accessibility

### Built-in behavior
- Enforces the use of native `<a>` and `<button>` HTML elements for keyboard and screen reader support by default

### Developer responsibilities
- Use `<a>` for navigation to new pages or different sections
- Use `<button>` for actions performed within the same page
- Give icon only buttons (`<daff-icon-button>`) a meaningful label using `aria-label` or `aria-labelledby`

## Deprecations
- `<daff-raised-button>` is deprecated and will be removed in v1.0.0. Use the `elevated` property instead.
- `<daff-underline-button>` is deprecated and will be removed in v1.0.0.