# Button

Source: https://material.spynejs.com/components/buttons
Part of: Material shell gallery, Google's Material Design 3 for SpyneJS. Index: https://material.spynejs.com/llms.txt

Material's common button, in five variants, five sizes and two shapes. In an app on the Material template a button is not a component you import: it is the class `btn` with classes for its look, and an app model asks for the look with a `button` key.

## In an app model

A call to action says how its button looks in a `button` key beside its words:

```json
{
  "ctaText": "Order ahead",
  "attrCtaHref": "/order",
  "button": {
    "variant": "tonal",
    "size": "md",
    "shape": "square"
  }
}
```

| Key of `button` | Values | Left out |
| --- | --- | --- |
| `variant` | `filled`, `tonal`, `outlined`, `elevated`, `text` | `filled` |
| `size` | `xs`, `sm`, `md`, `lg`, `xl` | `sm` |
| `shape` | `round`, `square` | `round` |

- Write only what is not a default. With the whole look at its defaults, leave `button` out.
- With no `button` key the button is written `btn btn-primary`, which draws as the filled button at the small size.
- A `button` key with nothing in it, or with only defaults in it, is written `btn btn-filled btn-sm`. That draws the same.
- The key is read where a call to action is: a page’s `hero`, a call-to-action banner (`cta-banner.tmpl.html`), each row of a split feature (`split-feature.tmpl.html`), and the contact form’s data beside `formFields`.
- A model does not say whether a button is disabled.
- To have no button, give `ctaText` no words (`""`). A call to action with no words has no button drawn.
- The contact form’s button has no `ctaText`. Its words, “Send Message”, are in the form’s template.

## The classes

`btn`, then one class for the variant, one for the size, and `btn-square` for the square shape:

```
btn btn-tonal btn-md btn-square
```

| Choice | Classes |
| --- | --- |
| Variant | `btn-filled`, `btn-tonal`, `btn-outlined`, `btn-elevated`, `btn-text` |
| Size | `btn-xs`, `btn-sm`, `btn-md`, `btn-lg`, `btn-xl` |
| Shape | `btn-square` (round needs no class) |

- A template of your own can write these classes directly on an `<a>` or a `<button>`.
- Disabled is the attribute `disabled`, or `aria-disabled="true"` on a link.

## Where it is in the template

| File | What it holds | By name |
| --- | --- | --- |
| `src/app/traits/utils/material-button-options.js` | the keys, their values and defaults; the classes for a look | `MATERIAL_BUTTON_OPTIONS` |
| `src/app/traits/page/page-item-core-traits.js` | turns the `button` key into `attrButtonClass` before a template renders | `pageItemCore$GiveButtonLook` |
| `src/scss/00-spynejs-design-system/elements/_buttons.scss` | the styles |  |

The template is public: https://github.com/spynejs/application-shell-material. An app made from it has these same files.

What it rests on in `@spynejs/grammar`: `op:shape-data-for-logicless-template`, `op:attr-prefix-for-attribute-placeholders`, `op:default-class-with-sparse-exceptions`.

## As the page shows it

The page’s own words, in its own order, read from the page as it is drawn in the light colour scheme. They were written for someone looking at the page: “above”, “below” and “marked” mean the drawn page. A thing the page draws is named here in its place (`Button:`, `Field:`, `Switch:`), and a box that reports what the reader does is as it starts, empty. What depends on the reader’s own window is left out.

Press a choice to change the button. Under it are the classes the template then writes, and the piece of an app model that asks for it.

Button: Order ahead

- Variant: **Filled** (shown), Tonal, Outlined, Elevated, Text
- Size: Extra small, Small, **Medium** (shown), Large, Extra large
- Shape: **Round** (shown), Square
- State: **Enabled** (shown), Disabled

### Classes

```
btn btn-filled btn-md
```

### In the app model

```json
{
  "ctaText": "Order ahead",
  "attrCtaHref": "/order",
  "button": {
    "size": "md"
  }
}
```

A model says how a button looks in a button key, beside the call to action’s words, ctaText: in the hero, the call-to-action banner, each row of the split feature, and the contact form. Only what is not a default is written. With no button key the template writes btn-primary, which draws as the filled button at the small size. A model does not say whether a button is disabled, so the State choice changes the button here and not the model. The From a model page shows the key at work.
