---
metaTitle: Button component | AwesCode UI
meta:
  - name: description
    content: The <AwButton /> component is used to render Button - UI Vue component for AwesCode UI.
title: Button
---

# Button

**Category:** Molecule | **Import:** Global

The `AwButton` component is a versatile button with multiple themes, sizes, colors, and states.

## Overview

`AwButton` provides a comprehensive button component that extends `AwLink` functionality, supporting routing, external links, and button actions. It includes loading states, icons, and various visual styles.

## Usage

### Basic Example

```markup
<AwButton>Click me</AwButton>
```

### With Icon

```markup
<AwButton icon="awesio/star">Favorite</AwButton>
```

### Different Themes

```markup
<AwButton theme="solid">Solid</AwButton>
<AwButton theme="outline">Outline</AwButton>
<AwButton theme="icon" icon="awesio/settings" />
```

### Different Sizes

```markup
<AwButton size="sm">Small</AwButton>
<AwButton size="md">Medium</AwButton>
<AwButton size="lg">Large</AwButton>
```

### With Loading State

```markup
<AwButton :loading="isLoading">Submit</AwButton>
```

### As Link

```markup
<AwButton href="/page">Go to Page</AwButton>
<AwButton href="https://example.com">External Link</AwButton>
```

## API

### Props

| Name | Description | Type | Required | Default |
|------|-------------|------|----------|---------|
| size | Button size (xs, sm, md, lg) | `String` | `false` | `'md'` |
| color | Button color - see [Built-in Colors](/reference/colors) | `String` | `false` | `'accent'` |
| theme | Button theme (solid, outline, icon) | `String` | `false` | `'solid'` |
| icon | Leading icon name - see [Built-in Icons](/reference/icons) | `String` | `false` | `''` |
| iconRight | Trailing icon name - see [Built-in Icons](/reference/icons) | `String` | `false` | `''` |
| loading | Show loading spinner | `Boolean` / `String` | `false` | `false` |
| locked | Show lock icon and disable | `Boolean` | `false` | `false` |
| lockedTooltip | Tooltip when locked | `String` | `false` | `''` |
| hideText | Hide button text | `Boolean` | `false` | `false` |
| autoWidth | Auto width (no full width) | `Boolean` | `false` | `false` |
| highlightIcon | Highlight icon (lg size only) | `Boolean` | `false` | `false` |

All link-related props from `AwLink` are also supported (e.g., `href`, `text`).

### Slots

| Name | Description | Props | Default Slot Content |
|------|-------------|-------|---------------------|
| default | Button text content | `{ text }` | Text prop value |
| icon | Custom leading icon | `{ icon }` | Default icon |
| icon-right | Custom trailing icon | `{ iconRight }` | Default icon |

### Events

All standard button/link events are supported (e.g., `click`).

### Config Options

The component uses default configuration from `@AwConfig`:

```javascript
export default {
  AwButton: {
    routerComponent: 'router-link',
    size: 'md',
    color: 'accent',
    theme: 'solid'
  }
}
```

## Component Behavior

### Link and Routing

`AwButton` extends `AwLink`, providing intelligent routing behavior through the `href` prop:

**Internal Navigation:**
```markup
<AwButton href="/dashboard">Go to Dashboard</AwButton>
```
- Automatically uses the router component (e.g., `router-link` or `nuxt-link`)
- No need to specify `to` prop - just use `href`
- Preserves SPA navigation without page reload

**External Links:**
```markup
<AwButton href="https://example.com">Visit Site</AwButton>
```
- Automatically renders as standard `<a>` tag for external URLs
- Opens in same window unless `target` attribute specified

The component automatically detects whether a link is internal or external and renders the appropriate element.

### Button States

**Loading State:**
- Shows spinner icon overlay
- Disables button interaction
- Maintains button dimensions
- Loading spinner uses current color theme

**Locked State:**
- Shows lock icon overlay
- Disables button interaction
- Optional tooltip via `lockedTooltip` prop
- Useful for premium features or permission-restricted actions

**Disabled State:**
- Standard HTML disabled attribute
- Visual styling via CSS
- Prevents all interactions

**State Priority:**
If multiple states are active:
1. Loading state takes precedence (shows spinner)
2. Locked state shows if not loading (shows lock)
3. Disabled state is independent

### Icon Highlighting

Icon highlighting creates a visual emphasis effect:
- Only available with `size="lg"` and `theme="solid"`
- Adds background circle behind icons
- Applies to both leading (`icon`) and trailing (`iconRight`) icons
- Automatically disabled for other size/theme combinations

### Animated Icons

The component automatically detects and applies animations to supported icon names:
- No additional props needed
- Animation triggers on parent hover (via `aw-animated-icon-parent` class)
- Enhances interactivity without JavaScript

### Text Visibility

Control button text display with the `hideText` prop:
- Useful for icon-only buttons with accessible labels
- Works with `aria-label` for screen readers
- Maintains proper spacing and layout

## Related Components

- `AwActionButton` - Action button with descriptions
- `AwButtonNav` - Navigation button
- `AwLink` - Basic link component

## Notes

- **Import Method:** Global - Available as molecule component
- Extends `AwLink` for routing and link functionality
- Supports animated icons (automatically detected)
- Icon highlighting only works with `size="lg"` and `theme="solid"`
- Loading state shows spinner and disables button
- Locked state shows lock icon and disables button
- Custom themes and colors are supported via CSS classes