> Part of the [Tangram component index](/docs/components/index.md). Use the index to find other components.

# Button (Tangram 2)

Apply `tg2Button` to a `<button>` or an `<a>`. Both elements get the same visual style.

- Use `<button tg2Button>` for an action.
- Use `<a tg2Button href="...">` for navigation.
- Use `tg2Style="watchlist"` with `[toggled]` for the watchlist toggle.

```html
<button tg2Button>Search</button>
<button
    tg2Button
    tg2Style="secondary"
    size="medium">
    Save
</button>
<a
    tg2Button
    tg2Style="transparent"
    href="/listings"
    >View all</a
>
```

## Hide the label

Two inputs hide the label. You cannot use them together.

- `[iconOnly]="true"` hides the label at every viewport size. Use it when the icon alone is clear, for example a close or delete action.
- `iconOnlyBelow="sm"` or `"md"` hides the label only below that breakpoint. Use it when the label helps on large screens, but the button must be smaller on mobile.

`iconOnlyBelow` uses CSS only, so it does not cause a hydration flash. The label text stays in the DOM for screen readers.

```html
<button
    tg2Button
    [iconOnly]="true"
    aria-label="Close">
    <tg-icon-left
        name="basic-cross"
        aria-hidden="true"></tg-icon-left>
</button>
```

## Toggle buttons: change the icon and label

Keep `<tg-icon-left>` as an unconditional child. Change only its `name` and the label text.

Do:

```html
<button
    tg2Button
    tg2Style="watchlist"
    [toggled]="isWatchlisted()"
    (click)="isWatchlisted.set(!isWatchlisted())">
    <tg-icon-left
        [name]="isWatchlisted() ? 'binoculars-tick' : 'binoculars-plus'"
        size="small"
        aria-hidden="true"></tg-icon-left>
    {{ isWatchlisted() ? 'Watchlisted' : 'Add to Watchlist' }}
</button>
```

Do not put the icon and the label inside `@if` / `@else`. An [Angular content-projection limitation](https://github.com/angular/angular/issues/55462) then puts the icon inside the label, not beside it. Angular shows no error.

<!-- prettier-ignore -->
```html
<!-- Wrong: the icon renders inside the label -->
<button tg2Button tg2Style="watchlist" [toggled]="isWatchlisted()">
    @if (isWatchlisted()) {
        <tg-icon-left name="binoculars-tick" size="small" aria-hidden="true"></tg-icon-left>
        Watchlisted
    } @else {
        <tg-icon-left name="binoculars-plus" size="small" aria-hidden="true"></tg-icon-left>
        Add to Watchlist
    }
</button>
```

## Disabled links

A `disabled` attribute on `<a tg2Button>` stops the navigation. It does not stop your `(click)` handler. Check the disabled state in your handler.

<!-- generated:api:start -->
<!-- Generated from tg2-button.component.ts by npm run docs:components. Do not edit by hand. -->

## API

Selector: `a[tg2Button], button[tg2Button]`. Import `Tg2ButtonComponent` from `@trademe/tangram`.

Experimental: the API can change in a minor release.

### Inputs

- `theme`: `tg2-light` | `tg2-dark` | `tg-light` | `tg-dark`. Default `tg2-light`.
- `tg2Style`: `primary` | `secondary` | `transparent` | `destructive` | `expressive` | `enhanced` | `watchlist`. Default `primary`.
- `size`: `small` | `medium` | `large`. Default `large`. Not with `autoSize`.
- `autoSize`: `small` | `medium`. Not with `size`.
- `shape`: `round` | `square`. Default `square`.
- `toggled`: `boolean`.
- `iconOnly`: `boolean`. Default `false`. Not with `iconOnlyBelow`.
- `iconOnlyBelow`: `sm` | `md`. Not with `iconOnly`.
- `loading`: `boolean`. Default `false`.
- `fullWidth`: `boolean`. Default `false`. Not with `tag`, `linkStyle`.
- `type`: `button` | `submit` | `reset`. Default `button`.
- `tag`: `boolean`. Default `false`. Not with `linkStyle`, `fullWidth`. Needs `theme` `tg-light` or `tg-dark`, set before this input in the template.
- `linkStyle`: `boolean`. Default `false`. Not with `tag`, `fullWidth`. Needs `theme` `tg-light` or `tg-dark`, set before this input in the template.

### Content slots

- `tg-icon, tg-icon-left`
- Default content
- `tg-icon-right`

<!-- generated:api:end -->
