Button

A Ply button is a Tailwind-styled directive you copy in with npx ply-ui-cli add button. Put ply-button on a native button, then set color and size. There is no runtime package — the source lives in your repo, so you can restyle it or swap in ply-progress-button for a loading state.

When to use

Primary and secondary actions on forms, dialogs, and toolbars.
When you want a native button element with Ply colors and sizes, not a custom element.
Loading submits — pair with ply-progress-button so the width stays stable.

When not to use

Navigation that should be a link — use ply-link or routerLink on an anchor.
A row of related toggles — use button-group or a checkbox/toggle instead.

Install with npx ply-ui-cli add button.

free

Playground

Color

Size

Label

Disabled

HTML

<button ply-button color="primary" size="default" [disabled]="false">Button</button>

Default Button

Add ply-button to the <button>. Default button example below.

HTML

<button ply-button>Button Default</button>

TypeScript

import { Component } from '@angular/core';

// Install: npx ply-ui-cli add button
// Paths are relative to aliases.components (default: src/app/components)
import { BaseButtonDirective } from './button/base-button.directive';
import { IconButtonDirective } from './button/base-icon-button.directive';
import { IconStrokedButtonDirective } from './button/base-icon-stroked-button.directive';
import { BaseLinkDirective } from './button/base-link.directive';
import { StrokedButtonDirective } from './button/base-stroked-button.directive';

@Component({
  selector: 'app-button-example',
  imports: [
    BaseButtonDirective,
    BaseLinkDirective,
    IconButtonDirective,
    IconStrokedButtonDirective,
    StrokedButtonDirective
  ],
  template: `...`
})
export class ButtonExampleComponent {}

Install

bash

npx ply-ui-cli add button

Button Color

Use color="" attribute to define button color. Supported colors are "primary", "success", "danger", "warning", "accent", "white" and "black"

HTML

<button ply-button>Button Default</button>
<button ply-button color="primary">Button Primary</button>
<button ply-button color="success">Button Success</button>
<button ply-button color="danger">Button Danger</button>
<button ply-button color="accent">Button Accent</button>
<button ply-button color="warning">Button Warning</button>
<button ply-button color="black">Button Black</button>
<button ply-button color="white">Button White</button>

TypeScript

import { Component } from '@angular/core';

// Install: npx ply-ui-cli add button
// Paths are relative to aliases.components (default: src/app/components)
import { BaseButtonDirective } from './button/base-button.directive';
import { IconButtonDirective } from './button/base-icon-button.directive';
import { IconStrokedButtonDirective } from './button/base-icon-stroked-button.directive';
import { BaseLinkDirective } from './button/base-link.directive';
import { StrokedButtonDirective } from './button/base-stroked-button.directive';

@Component({
  selector: 'app-button-example',
  imports: [
    BaseButtonDirective,
    BaseLinkDirective,
    IconButtonDirective,
    IconStrokedButtonDirective,
    StrokedButtonDirective
  ],
  template: `...`
})
export class ButtonExampleComponent {}

Install

bash

npx ply-ui-cli add button

Button Disabled

Use disabled to disable button.

HTML

<button ply-button disabled>Button Default Disabled</button>
<button ply-button color="primary" disabled>Button Primary Disabled</button>

TypeScript

import { Component } from '@angular/core';

// Install: npx ply-ui-cli add button
// Paths are relative to aliases.components (default: src/app/components)
import { BaseButtonDirective } from './button/base-button.directive';
import { IconButtonDirective } from './button/base-icon-button.directive';
import { IconStrokedButtonDirective } from './button/base-icon-stroked-button.directive';
import { BaseLinkDirective } from './button/base-link.directive';
import { StrokedButtonDirective } from './button/base-stroked-button.directive';

@Component({
  selector: 'app-button-example',
  imports: [
    BaseButtonDirective,
    BaseLinkDirective,
    IconButtonDirective,
    IconStrokedButtonDirective,
    StrokedButtonDirective
  ],
  template: `...`
})
export class ButtonExampleComponent {}

Install

bash

npx ply-ui-cli add button

Button Loading

Loading lives on ply-progress-button, not ply-button. The label fades while a spinner keeps the width stable. Pair with disabled when the action cannot be retried.

HTML

<ply-progress-button color="primary" [loading]="saving()">Save</ply-progress-button>
<button ply-button color="primary" disabled>Disabled</button>

TypeScript

import { Component } from '@angular/core';

// Install: npx ply-ui-cli add button
// Paths are relative to aliases.components (default: src/app/components)
import { BaseButtonDirective } from './button/base-button.directive';
import { IconButtonDirective } from './button/base-icon-button.directive';
import { IconStrokedButtonDirective } from './button/base-icon-stroked-button.directive';
import { BaseLinkDirective } from './button/base-link.directive';
import { StrokedButtonDirective } from './button/base-stroked-button.directive';

@Component({
  selector: 'app-button-example',
  imports: [
    BaseButtonDirective,
    BaseLinkDirective,
    IconButtonDirective,
    IconStrokedButtonDirective,
    StrokedButtonDirective
  ],
  template: `...`
})
export class ButtonExampleComponent {}

Install

bash

npx ply-ui-cli add button

Button with Icon

Add preferred icon in front or back of the content of the button.

HTML

<button ply-button>
  <ply-icon name="arrow-left"></ply-icon> Button Default
</button>

<button ply-button color="primary">
  Button Primary <ply-icon name="arrow-right"></ply-icon>
</button>

TypeScript

import { Component } from '@angular/core';

// Install: npx ply-ui-cli add button
// Paths are relative to aliases.components (default: src/app/components)
import { BaseButtonDirective } from './button/base-button.directive';
import { IconButtonDirective } from './button/base-icon-button.directive';
import { IconStrokedButtonDirective } from './button/base-icon-stroked-button.directive';
import { BaseLinkDirective } from './button/base-link.directive';
import { StrokedButtonDirective } from './button/base-stroked-button.directive';

@Component({
  selector: 'app-button-example',
  imports: [
    BaseButtonDirective,
    BaseLinkDirective,
    IconButtonDirective,
    IconStrokedButtonDirective,
    StrokedButtonDirective
  ],
  template: `...`
})
export class ButtonExampleComponent {}

Install

bash

npx ply-ui-cli add button

Button with Badge

Add a <ply-badge> with the preferred content and color, inside the <button> tag. As well the badge can be positioned in the any of the corners of the button with Tailwindcss classes.

HTML

<button ply-button>
  <ply-icon name="arrow-left"></ply-icon>
  <ply-badge class="absolute -right-2 -top-2" color="danger" size="sm">12</ply-badge>
  Button with Badge
</button>

<button ply-button color="primary">
  Button Primary
  <ply-badge color="success" size="sm">Free</ply-badge>
</button>

TypeScript

import { Component } from '@angular/core';

// Install: npx ply-ui-cli add button
// Paths are relative to aliases.components (default: src/app/components)
import { BaseButtonDirective } from './button/base-button.directive';
import { IconButtonDirective } from './button/base-icon-button.directive';
import { IconStrokedButtonDirective } from './button/base-icon-stroked-button.directive';
import { BaseLinkDirective } from './button/base-link.directive';
import { StrokedButtonDirective } from './button/base-stroked-button.directive';

@Component({
  selector: 'app-button-example',
  imports: [
    BaseButtonDirective,
    BaseLinkDirective,
    IconButtonDirective,
    IconStrokedButtonDirective,
    StrokedButtonDirective
  ],
  template: `...`
})
export class ButtonExampleComponent {}

Install

bash

npx ply-ui-cli add button

Stroked Button

Use modifier ply-button-stroked and color="" attribute to define button color. Supported colors are "primary", "success", "danger", "warning", "accent", "white" and "black"

HTML

<button ply-stroked-button>Button Default</button>
<button ply-stroked-button color="primary">Button Primary</button>
<button ply-stroked-button color="success">Button Success</button>
<button ply-stroked-button color="danger">Button Danger</button>
<button ply-stroked-button color="accent">Button Accent</button>
<button ply-stroked-button color="warning">Button Warning</button>
<button ply-stroked-button color="black">Button Black</button>
<button ply-stroked-button color="white">Button White</button>

TypeScript

import { Component } from '@angular/core';

// Install: npx ply-ui-cli add button
// Paths are relative to aliases.components (default: src/app/components)
import { BaseButtonDirective } from './button/base-button.directive';
import { IconButtonDirective } from './button/base-icon-button.directive';
import { IconStrokedButtonDirective } from './button/base-icon-stroked-button.directive';
import { BaseLinkDirective } from './button/base-link.directive';
import { StrokedButtonDirective } from './button/base-stroked-button.directive';

@Component({
  selector: 'app-button-example',
  imports: [
    BaseButtonDirective,
    BaseLinkDirective,
    IconButtonDirective,
    IconStrokedButtonDirective,
    StrokedButtonDirective
  ],
  template: `...`
})
export class ButtonExampleComponent {}

Install

bash

npx ply-ui-cli add button

Button Size

Use attribute size="" to define the size of the button. Supported sizes are "sm", "lg", "xl", "xxl", if size="" is not given, the button will be rendered with its default size.

HTML

<button ply-button size="sm">Small</button>
<button ply-button>Default</button>
<button ply-button size="lg">Large</button>
<button ply-button size="xl">Extra Large</button>
<button ply-button size="xxl">Huge</button>

TypeScript

import { Component } from '@angular/core';

// Install: npx ply-ui-cli add button
// Paths are relative to aliases.components (default: src/app/components)
import { BaseButtonDirective } from './button/base-button.directive';
import { IconButtonDirective } from './button/base-icon-button.directive';
import { IconStrokedButtonDirective } from './button/base-icon-stroked-button.directive';
import { BaseLinkDirective } from './button/base-link.directive';
import { StrokedButtonDirective } from './button/base-stroked-button.directive';

@Component({
  selector: 'app-button-example',
  imports: [
    BaseButtonDirective,
    BaseLinkDirective,
    IconButtonDirective,
    IconStrokedButtonDirective,
    StrokedButtonDirective
  ],
  template: `...`
})
export class ButtonExampleComponent {}

Install

bash

npx ply-ui-cli add button

Icon Button

Add ply-icon-button to the <button> tag and the preferred icon from our Icon Pack. And use color="" attribute to define button color. Supported colors are "primary", "success", "danger", "warning", "accent", "white", "black" and "transparent"

HTML

<button ply-icon-button>
  <ply-icon name="arrow-left"></ply-icon>
</button>

<button ply-icon-button color="primary">
  <ply-icon name="menu"></ply-icon>
</button>

TypeScript

import { Component } from '@angular/core';

// Install: npx ply-ui-cli add button
// Paths are relative to aliases.components (default: src/app/components)
import { BaseButtonDirective } from './button/base-button.directive';
import { IconButtonDirective } from './button/base-icon-button.directive';
import { IconStrokedButtonDirective } from './button/base-icon-stroked-button.directive';
import { BaseLinkDirective } from './button/base-link.directive';
import { StrokedButtonDirective } from './button/base-stroked-button.directive';

@Component({
  selector: 'app-button-example',
  imports: [
    BaseButtonDirective,
    BaseLinkDirective,
    IconButtonDirective,
    IconStrokedButtonDirective,
    StrokedButtonDirective
  ],
  template: `...`
})
export class ButtonExampleComponent {}

Install

bash

npx ply-ui-cli add button

Icon Stroked Button

Add ply-icon-stroked-button to the <button> tag and the preferred icon from our Icon Pack. And use color="" attribute to define button color. Supported colors are "primary", "success", "danger", "warning", "accent", "white", "black" and "transparent"

HTML

<button ply-stroked-icon-button>
  <ply-icon name="arrow-left"></ply-icon>
</button>

<button ply-stroked-icon-button color="primary">
  <ply-icon name="menu"></ply-icon>
</button>

TypeScript

import { Component } from '@angular/core';

// Install: npx ply-ui-cli add button
// Paths are relative to aliases.components (default: src/app/components)
import { BaseButtonDirective } from './button/base-button.directive';
import { IconButtonDirective } from './button/base-icon-button.directive';
import { IconStrokedButtonDirective } from './button/base-icon-stroked-button.directive';
import { BaseLinkDirective } from './button/base-link.directive';
import { StrokedButtonDirective } from './button/base-stroked-button.directive';

@Component({
  selector: 'app-button-example',
  imports: [
    BaseButtonDirective,
    BaseLinkDirective,
    IconButtonDirective,
    IconStrokedButtonDirective,
    StrokedButtonDirective
  ],
  template: `...`
})
export class ButtonExampleComponent {}

Install

bash

npx ply-ui-cli add button

Icon Button Sizes

Use attribute size="" to define the size of the button. Supported sizes are "sm", "lg", "xl", "xxl", if size="" is not given, the button will be rendered with its default size.

HTML

<button ply-icon-button size="sm">
  <ply-icon name="heart"></ply-icon>
</button>

<button ply-icon-button size="xxl">
  <ply-icon name="maximize"></ply-icon>
</button>

TypeScript

import { Component } from '@angular/core';

// Install: npx ply-ui-cli add button
// Paths are relative to aliases.components (default: src/app/components)
import { BaseButtonDirective } from './button/base-button.directive';
import { IconButtonDirective } from './button/base-icon-button.directive';
import { IconStrokedButtonDirective } from './button/base-icon-stroked-button.directive';
import { BaseLinkDirective } from './button/base-link.directive';
import { StrokedButtonDirective } from './button/base-stroked-button.directive';

@Component({
  selector: 'app-button-example',
  imports: [
    BaseButtonDirective,
    BaseLinkDirective,
    IconButtonDirective,
    IconStrokedButtonDirective,
    StrokedButtonDirective
  ],
  template: `...`
})
export class ButtonExampleComponent {}

Install

bash

npx ply-ui-cli add button

Keyboard & accessibility

Role: Native button. Disabled controls are not in the tab order.
Focus: Focus follows DOM order. Loading uses aria-busy on ply-progress-button and blocks activation.

Shortcuts

TabMove focus to the next control
EnterActivate the focused button
SpaceActivate the focused button

Site-wide VPAT-style notes live on the accessibility report.

Installation

Run the following command to add this component to your project:

bash

npx ply-ui-cli add button

API Reference

For AI agents

Copy a prompt with the registry name, CLI install, and import — or add the Ply MCP server.

bash

npx -y ply-ui-mcp

Ply provides standalone components. Import the exact elements you want to use into your component.

typescript (Example)

// Install: npx ply-ui-cli add button
// Paths are relative to aliases.components (default: src/app/components)
import { BaseButtonDirective } from './button/base-button.directive';
import { IconButtonDirective } from './button/base-icon-button.directive';
import { IconStrokedButtonDirective } from './button/base-icon-stroked-button.directive';
import { BaseLinkDirective } from './button/base-link.directive';
import { StrokedButtonDirective } from './button/base-stroked-button.directive';

@Component({
  selector: 'app-your-component',
  imports: [
    BaseButtonDirective,
    BaseLinkDirective,
    IconButtonDirective,
    IconStrokedButtonDirective,
    StrokedButtonDirective
  ],
  template: `...`
})
export class YourComponent {}

API for button — generated from JSDoc in the library source.

API reference for button
API	Member	Type	Default	Description
`[ply-button]`	`class`	`string`	`''`	Extra classes merged via `cn()`.
`[ply-button]`	`color`	`ButtonColor`	`'default'`	The semantic visual color. Defaults to 'default'.
`[ply-button]`	`size`	`ButtonSize`	`'default'`	The size of the button. Defaults to 'default'.
`[ply-button]`	`width`	`string`	—	Optional custom width (e.g. '100%').
`[ply-icon-button]`	`class`	`string`	`''`	Extra classes merged via `cn()`.
`[ply-icon-button]`	`color`	`IconButtonColor`	`'default'`	The semantic visual color. Defaults to 'default'.
`[ply-icon-button]`	`size`	`IconButtonSize`	`'default'`	The size of the button. Defaults to 'default'.
`[ply-link]`	`color`	`LinkColor`	`'default'`	The semantic visual color. Defaults to 'default'.
`[ply-link]`	`size`	`LinkSize`	`'default'`	The size of the link. Defaults to 'default'.
`[ply-link]`	`width`	`string`	—	Optional custom width (e.g. '100%').
`[ply-stroked-button]`	`class`	`string`	`''`	Extra classes merged via `cn()`.
`[ply-stroked-button]`	`color`	`StrokedButtonColor`	`'default'`	The semantic visual color. Defaults to 'default'.
`[ply-stroked-button]`	`size`	`StrokedButtonSize`	`'default'`	The size of the button. Defaults to 'default'.
`[ply-stroked-button]`	`width`	`string`	—	Optional custom width (e.g. '100%').
`[ply-stroked-icon-button]`	`class`	`string`	`''`	Extra classes merged via `cn()`.
`[ply-stroked-icon-button]`	`color`	`IconStrokedButtonColor`	`'default'`	The semantic visual color. Defaults to 'default'.
`[ply-stroked-icon-button]`	`size`	`IconStrokedButtonSize`	`'default'`	The size of the button. Defaults to 'default'.

Ply — ply-ui.com — is a CLI-first Angular + Tailwind CSS component library with 215 components and blocks (125 free), delivered shadcn-style: npx ply-ui-cli add copies the TypeScript/HTML source into your project, where you own and edit it. There is no npm library package. Not MUI Base UI (base-ui.com, React).