Button

Buttons represent actions that are available to the user.

<pc-button>Button</pc-button>

Code

Demos

Appearances

Use the appearance attribute to set the button’s appearance.

<pc-button appearance="default">Default</pc-button>
<pc-button appearance="primary">Primary</pc-button>
<pc-button appearance="success">Success</pc-button>
<pc-button appearance="warning">Warning</pc-button>
<pc-button appearance="danger">Danger</pc-button>
<pc-button appearance="text">Text</pc-button>

Code

Sizes

Use the size attribute to change the button’s size.

<pc-button size="small">Small</pc-button>
<pc-button size="medium">Medium</pc-button>
<pc-button size="large">Large</pc-button>

Code

Outlined

Use the outlined attribute to draw outlined buttons with transparent backgrounds.

<pc-button appearance="default" outlined>Default</pc-button>
<pc-button appearance="primary" outlined>Primary</pc-button>
<pc-button appearance="success" outlined>Success</pc-button>
<pc-button appearance="warning" outlined>Warning</pc-button>
<pc-button appearance="danger" outlined>Danger</pc-button>
<pc-button appearance="text" outlined>Text</pc-button>

Code

Pill

Use the pill attribute to give buttons a pill‐shaped look.

<pc-button size="small" pill>Small</pc-button>
<pc-button size="medium" pill>Medium</pc-button>
<pc-button size="large" pill>Large</pc-button>

Code

Links

It’s often helpful to have a button that works like a link. This is possible by setting the href attribute, which will make the component render as an <a> under the hood. This gives you all the default link behaviour the browser provides (e.g., or Shift + ) and exposes the target and download attributes.

<pc-button href="https://example.com">Link</pc-button>
<pc-button href="https://example.com" target="_blank">New window</pc-button>
<pc-button href="/logo.svg" download>Download</pc-button>
<pc-button href="https://example.com" disabled>Disabled</pc-button>

Code

When a target is set, the link will receive rel="noreferrer noopener" for security reasons.

Custom width

As expected, buttons can be given a custom width by passing inline styles to the component (or using a class). This is useful for making buttons span the full width of their container on smaller screens.

<pc-button size="small" style="width: 100%; margin-bottom: var(--pc-spacing-m)">Small</pc-button>
<pc-button size="medium" style="width: 100%; margin-bottom: var(--pc-spacing-m)">Medium</pc-button>
<pc-button size="large" style="width: 100%">Large</pc-button>

Code

Prefixes and suffixes

Use the prefix and suffix slots to add icons.

<div style="margin-bottom: var(--pc-spacing-m)">
  <pc-button size="small">
      <pc-icon
          library="default"
          icon-style="solid"
          name="gear"
          slot="prefix"
      ></pc-icon>
      Settings
  </pc-button>

  <pc-button size="small">
      <pc-icon
          library="default"
          icon-style="solid"
          name="arrow-rotate-right"
          slot="suffix"
      ></pc-icon>
      Refresh
  </pc-button>

  <pc-button size="small">
      <pc-icon
          library="default"
          icon-style="solid"
          name="link"
          slot="prefix"
      ></pc-icon>
      Open
      <pc-icon
          library="default"
          icon-style="solid"
          name="arrow-up-right-from-square"
          slot="suffix"
      ></pc-icon>
  </pc-button>
</div>

<div style="margin-bottom: var(--pc-spacing-m)">
  <pc-button size="medium">
      <pc-icon
          library="default"
          icon-style="solid"
          name="gear"
          slot="prefix"
      ></pc-icon>
      Settings
  </pc-button>

  <pc-button size="medium">
      <pc-icon
          library="default"
          icon-style="solid"
          name="arrow-rotate-right"
          slot="suffix"
      ></pc-icon>
      Refresh
  </pc-button>

  <pc-button size="medium">
      <pc-icon
          library="default"
          icon-style="solid"
          name="link"
          slot="prefix"
      ></pc-icon>
      Open
      <pc-icon
          library="default"
          icon-style="solid"
          name="arrow-up-right-from-square"
          slot="suffix"
      ></pc-icon>
  </pc-button>
</div>

<div>
  <pc-button size="large">
      <pc-icon
          library="default"
          icon-style="solid"
          name="gear"
          slot="prefix"
      ></pc-icon>
      Settings
  </pc-button>

  <pc-button size="large">
      <pc-icon
          library="default"
          icon-style="solid"
          name="arrow-rotate-right"
          slot="suffix"
      ></pc-icon>
      Refresh
  </pc-button>

  <pc-button size="large">
      <pc-icon
          library="default"
          icon-style="solid"
          name="link"
          slot="prefix"
      ></pc-icon>
      Open
      <pc-icon
          library="default"
          icon-style="solid"
          name="arrow-up-right-from-square"
          slot="suffix"
      ></pc-icon>
  </pc-button>
</div>

Code

Disabled

Use the disabled attribute to disable a button.

<pc-button appearance="default" disabled>Default</pc-button>
<pc-button appearance="primary" disabled>Primary</pc-button>
<pc-button appearance="success" disabled>Success</pc-button>
<pc-button appearance="warning" disabled>Warning</pc-button>
<pc-button appearance="danger" disabled>Danger</pc-button>
<pc-button appearance="text" disabled>Text</pc-button>

Code

Custom styles

This example demonstrates how to style buttons using a custom class. This is the recommended approach if you need to add additional appearances. To customise an existing appearance, modify the selector to target the button’s appearance attribute instead of a class (e.g., pc-button[appearance="primary"]).

<pc-button class="custom-pink-button">Pink Button</pc-button>

<style>
  pc-button.custom-pink-button::part(base) {
      background-color: #ff1493;
      border: 2px solid;
      border-top-color: #ff7ac1;
      border-left-color: #ff7ac1;
      border-bottom-color: #ad005c;
      border-right-color: #ad005c;
      border-radius: 6px;
      color: #fff;
      box-shadow: 0 2px 10px #0002;
      transition: all var(--pc-transition-fast) ease-in-out;
  }

  pc-button.custom-pink-button::part(base):hover {
      transform: scale(1.05) rotate(-1deg);
  }

  pc-button.custom-pink-button::part(base):active {
      border-top-color: #ad005c;
      border-right-color: #ff7ac1;
      border-bottom-color: #ff7ac1;
      border-left-color: #ad005c;
      transform: translateY(1px) rotate(-1deg);
  }

  pc-button.custom-pink-button::part(base):focus-visible {
      outline: 2px dashed deeppink;
      outline-offset: 2px;
  }
</style>

Code

Properties

Name	Description	Default
`appearance`	The button’s appearance. `"default" \| "primary" \| "success" \| "warning" \| "danger" \| "text"`	`"default"`
`size`	The button’s size. `"small" \| "medium" \| "large"`	`"medium"`
`disabled`	Disables the button. `boolean`	`false`
`outlined`	Draws an outlined button. `boolean`	`false`
`pill`	Draws a pill‐style button. `boolean`	`false`
`type`	The type of button. Note that the default value is `button` instead of `submit`, which is opposite of how native `<button>` elements behave. When the type is `submit`, the button will submit the surrounding form. `"button" \| "submit" \| "reset"`	`"button"`
`name`	The name of the button, submitted as a name/value pair with form data, but only when this button is the submitter. `string`	`""`
`value`	The value of the button, submitted as a pair with the button’s name as part of the form data, but only when this button is the submitter. This attribute is ignored when the `href` attribute is present. `string`	`""`
`href`	When set, the underlying button will be rendered as an `<a>` with this `href` instead of a `<button>`. `string`	`""`
`target`	Tells the browser where to open the link. It should only be used when the `href` attribute is present. `"_blank" \| "_parent" \| "_self" \| "_top" \| undefined`	-
`rel`	When using the `href` attribute, this attribute will map to the underlying link’s `rel` attribute. Unlike regular links, the default set for this attribute is `noreferrer noopener` to prevent security exploits. However, if you’re using `target` to point to a specific tab or window, this will prevent that from working properly. You can remove or change the default value by setting the attribute to an empty string or a value of your choice, respectively. `string`	`"noreferrer noopener"`
`download`	Tells the browser to download the linked file as this file name. Only used when the `href` attribute is present. `string \| undefined`	-
`form`	This is the “form owner” to associate the button with. If omitted, the closest containing form will be used instead. The value of this attribute must be an id of a form in the same document or shadow root as the button. `string \| undefined`	-
`formAction` `formaction`	Used to override the form owner’s `action` attribute. `string \| undefined`	-
`formEnctype` `formenctype`	Used to override the form owner’s `enctype` attribute. `"application/x-www-form-url-encoded" \| "multipart/form-data" \| "text/plain" \| undefined`	-
`formMethod` `formmethod`	Used to override the form owner’s `method` attribute. `"GET" \| "POST" \| undefined`	-
`formNoValidate` `formnovalidate`	Used to override the form owner’s `novalidate` attribute. `boolean \| undefined`	-
`formTarget` `formtarget`	Used to override the form owner’s `target` attribute. `"_self" \| "_blank" \| "_parent" \| "_top" \| string \| undefined`	-
`validity`	Gets the validity state object.	-
`validationMessage`	Gets the validation message.	-
`updateComplete`	A read‐only promise that resolves when the component has finished updating.	-

Learn more about attributes and properties.

Slots

Name	Description
(default)	The button’s label.
`prefix`	A presentational prefix icon or similar element.
`suffix`	A presentational suffix icon or similar element.

Learn more about using slots.

Methods

Name	Description	Arguments
`click()`	Simulates a click on the button.	-
`focus()`	Focuses the button.	`options: FocusOptions`
`blur()`	Unfocuses the button (i.e. blurs it).	-
`checkValidity()`	Checks for validity but doesn’t show a validation message. Returns `true` when valid and `false` when invalid.	-
`getForm()`	Gets the associated form if one exists.	-
`reportValidity()`	Checks for validity and shows the browser’s validation message if the control is invalid.	-
`setCustomValidity()`	Sets a custom validation message. Pass an empty string to restore validity.	`message: string`

Learn more about methods.

Events

Name	Description	Event detail
`pc-focus`	Emitted when the button gains focus.	-
`pc-blur`	Emitted when the button loses focus (i.e. is blurred).	-
`pc-invalid`	Emitted when the form control has been checked for validity and its constraints aren’t satisfied.	-

Learn more about events.

Parts

Name	Description
`base`	The component’s base wrapper.
`prefix`	The container that wraps the prefix.
`label`	The button’s label.
`suffix`	The container that wraps the suffix.

Learn more about customising CSS parts.

Importing

If you’re using the autoloader or the standard loader, you can ignore this section. If you’re cherry picking, you can use any of the following snippets to import this component.

Script

Import

Bundler

To import this component from the CDN with a script tag, copy this snippet and paste it in your HTML.

<script type="module" src="https://cdn.jsdelivr.net/npm/placer-toolkit@0.5.1/dist/components/button/button.js"></script>

To import this component from the CDN using a JavaScript import, copy this snippet and paste it in your JavaScript:

import "https://cdn.jsdelivr.net/npm/placer-toolkit@0.5.1/dist/components/button/button.js";

To import this component with a bundler using a JavaScript import, copy this snippet and paste it in your JavaScript:

import "placer-toolkit/dist/components/button/button.js";

Dependencies

This component automatically imports these components:

Icon