Skip to content

docs(material/button): update button documentation and examples for M3 #29252

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
amysorto merged 1 commit into from
Jun 13, 2024
Merged

docs(material/button): update button documentation and examples for M3 #29252

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
62 changes: 23 additions & 39 deletions src/components-examples/material/button/button-overview/button-overview-example.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,6 @@
<div class="example-label">Basic</div>
<div class="example-button-row">
<button mat-button>Basic</button>
<button mat-button color="primary">Primary</button>
<button mat-button color="accent">Accent</button>
<button mat-button color="warn">Warn</button>
<button mat-button disabled>Disabled</button>
<a mat-button href="https://www.google.com/" target="_blank">Link</a>
</div>
Expand All @@ -14,9 +11,6 @@
<div class="example-label">Raised</div>
<div class="example-button-row">
<button mat-raised-button>Basic</button>
<button mat-raised-button color="primary">Primary</button>
<button mat-raised-button color="accent">Accent</button>
<button mat-raised-button color="warn">Warn</button>
<button mat-raised-button disabled>Disabled</button>
<a mat-raised-button href="https://www.google.com/" target="_blank">Link</a>
</div>
Expand All @@ -26,9 +20,6 @@
<div class="example-label">Stroked</div>
<div class="example-button-row">
<button mat-stroked-button>Basic</button>
<button mat-stroked-button color="primary">Primary</button>
<button mat-stroked-button color="accent">Accent</button>
<button mat-stroked-button color="warn">Warn</button>
<button mat-stroked-button disabled>Disabled</button>
<a mat-stroked-button href="https://www.google.com/" target="_blank">Link</a>
</div>
Expand All @@ -38,9 +29,6 @@
<div class="example-label">Flat</div>
<div class="example-button-row">
<button mat-flat-button>Basic</button>
<button mat-flat-button color="primary">Primary</button>
<button mat-flat-button color="accent">Accent</button>
<button mat-flat-button color="warn">Warn</button>
<button mat-flat-button disabled>Disabled</button>
<a mat-flat-button href="https://www.google.com/" target="_blank">Link</a>
</div>
Expand All @@ -53,15 +41,6 @@
<button mat-icon-button aria-label="Example icon button with a vertical three dot icon">
<mat-icon>more_vert</mat-icon>
</button>
<button mat-icon-button color="primary" aria-label="Example icon button with a home icon">
<mat-icon>home</mat-icon>
</button>
<button mat-icon-button color="accent" aria-label="Example icon button with a menu icon">
<mat-icon>menu</mat-icon>
</button>
<button mat-icon-button color="warn" aria-label="Example icon button with a heart icon">
<mat-icon>favorite</mat-icon>
</button>
<button mat-icon-button disabled aria-label="Example icon button with a open in new tab icon">
<mat-icon>open_in_new</mat-icon>
</button>
Expand All @@ -74,20 +53,10 @@
<div class="example-button-row">
<div class="example-flex-container">
<div class="example-button-container">
<button mat-fab color="primary" aria-label="Example icon button with a delete icon">
<button mat-fab aria-label="Example icon button with a delete icon">
<mat-icon>delete</mat-icon>
</button>
</div>
<div class="example-button-container">
<button mat-fab color="accent" aria-label="Example icon button with a bookmark icon">
<mat-icon>bookmark</mat-icon>
</button>
</div>
<div class="example-button-container">
<button mat-fab color="warn" aria-label="Example icon button with a home icon">
<mat-icon>home</mat-icon>
</button>
</div>
<div class="example-button-container">
<button mat-fab disabled aria-label="Example icon button with a heart icon">
<mat-icon>favorite</mat-icon>
Expand All @@ -102,25 +71,40 @@
<div class="example-button-row">
<div class="example-flex-container">
<div class="example-button-container">
<button mat-mini-fab color="primary" aria-label="Example icon button with a menu icon">
<button mat-mini-fab aria-label="Example icon button with a menu icon">
<mat-icon>menu</mat-icon>
</button>
</div>
<div class="example-button-container">
<button mat-mini-fab color="accent" aria-label="Example icon button with a plus one icon">
<mat-icon>plus_one</mat-icon>
<button mat-mini-fab disabled aria-label="Example icon button with a home icon">
<mat-icon>home</mat-icon>
</button>
</div>
</div>
</div>
</section>
<section>
<div class="example-label">Extended Fab</div>
<div class="example-button-row">
<div class="example-flex-container">
<div class="example-button-container">
<button mat-mini-fab color="warn" aria-label="Example icon button with a filter list icon">
<mat-icon>filter_list</mat-icon>
<button mat-fab extended>
<mat-icon>favorite</mat-icon>
Basic
</button>
</div>
<div class="example-button-container">
<button mat-mini-fab disabled aria-label="Example icon button with a home icon">
<mat-icon>home</mat-icon>
<button mat-fab extended disabled>
<mat-icon>favorite</mat-icon>
Disabled
</button>
</div>
<div class="example-button-container">
<a mat-fab extended routerLink=".">
<mat-icon>favorite</mat-icon>
Link
</a>
</div>
</div>
</div>
</section>
8 changes: 0 additions & 8 deletions src/components-examples/material/button/button-types/button-types-example.css
View file
Open in desktop

This file was deleted.

129 changes: 0 additions & 129 deletions src/components-examples/material/button/button-types/button-types-example.html
View file
Open in desktop

This file was deleted.

16 changes: 0 additions & 16 deletions src/components-examples/material/button/button-types/button-types-example.ts
View file
Open in desktop

This file was deleted.

1 change: 0 additions & 1 deletion src/components-examples/material/button/index.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,3 @@
export {ButtonOverviewExample} from './button-overview/button-overview-example';
export {ButtonTypesExample} from './button-types/button-types-example';
export {ButtonDisabledInteractiveExample} from './button-disabled-interactive/button-disabled-interactive-example';
export {ButtonHarnessExample} from './button-harness/button-harness-example';
8 changes: 7 additions & 1 deletion src/material/button/button-base.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -107,7 +107,13 @@ export class MatButtonBase implements AfterViewInit, OnDestroy {
this._rippleLoader?.attachRipple(this._elementRef.nativeElement, v);
}

/** Theme color palette of the button */
/**
* Theme color palette of the button. This API is supported in M2 themes
* only, it has no effect in M3 themes.
*
* For information on applying color variants in M3, see
* https://material.angular.io/guide/theming#using-component-color-variants
*/
@Input() color?: string | null;

/** Whether the ripple effect is disabled or not. */
Expand Down
26 changes: 10 additions & 16 deletions src/material/button/button.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,26 +12,15 @@ There are several button variants, each applied as an attribute:

| Attribute | Description |
|----------------------|--------------------------------------------------------------------------|
| `mat-button` | Rectangular text button w/ no elevation |
| `mat-raised-button` | Rectangular contained button w/ elevation |
| `mat-flat-button` | Rectangular contained button w/ no elevation |
| `mat-stroked-button` | Rectangular outlined button w/ no elevation |
| `mat-button` | Rectangular text button w/ no elevation and rounded corners |
Copy link
Member

@crisbeto crisbeto Jun 13, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not sure if we should mention the appearance here since it can change based on the tokens. I know this was here before so totally fine to also just leave it.

Copy link
Contributor Author

@amysorto amysorto Jun 13, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah I was on the fence about that too, but technically the M3 specs call out that it has rounded corners and that is the default

| `mat-raised-button` | Rectangular contained button w/ elevation and rounded corners |
| `mat-flat-button` | Rectangular contained button w/ no elevation and rounded corners |
| `mat-stroked-button` | Rectangular outlined button w/ no elevation and rounded corners |
| `mat-icon-button` | Circular button with a transparent background, meant to contain an icon |
| `mat-fab` | Circular button w/ elevation, defaults to theme's accent color |
| `mat-fab` | Square button w/ elevation and rounded corners, meant to contain an icon. Can be [extended](https://material.angular.io/components/button/overview#extended-fab-buttons) to a rectangle to also fit a label |
| `mat-mini-fab` | Same as `mat-fab` but smaller |


### Theming
Buttons can be colored in terms of the current theme using the `color` property to set the
background color to `primary`, `accent`, or `warn`.

### Capitalization
According to the Material design spec button text has to be capitalized, however we have opted not
to capitalize buttons automatically via `text-transform: uppercase`, because it can cause issues in
certain locales. It is also worth noting that using ALL CAPS in the text itself causes issues for
screen-readers, which will read the text character-by-character. We leave the decision of how to
approach this to the consuming app.

### Extended fab buttons
Traditional fab buttons are circular and only have space for a single icon. However, you can add the
`extended` attribute to allow the fab to expand into a rounded rectangle shape with space for a text
Expand Down Expand Up @@ -64,6 +53,11 @@ default. A `<button>` element should be used for any interaction that _performs
current page_. An `<a>` element should be used for any interaction that _navigates to another
URL_. All standard accessibility best practices for buttons and anchors apply to `MatButton`.

#### Capitalization
Using ALL CAPS in the button text itself causes issues for screen-readers, which
will read the text character-by-character. It can also cause issues for localization.
We recommend not changing the default capitalization for the button text.

#### Disabling anchors
`MatAnchor` supports disabling an anchor in addition to the features provided by the native
`<a>` element. When you disable an anchor, the component sets `aria-disabled="true"` and
Expand Down