Porsche Design System

Button

Table of Contents

Usage
Custom states
Related components

Usage#

The following section provides guidance for designers and developers on how to use this component in different situations.

Do:

Use buttons for actions that have clear consequences, such as submitting a form or initiating a purchase.

Use buttons to indicate the next step in a process, such as "Continue" or "Next".

Use buttons with clear and concise labels that accurately describe the action they perform.

Use the primary button for the most important or desired action, and use the secondary button for less important or secondary actions.

Use icons in buttons to enhance their meaning, but ensure the icon is relevant and easily recognizable.

Use disabled buttons to indicate actions that are currently unavailable or incomplete, and provide context for why the button is disabled.

Don't:

Don't use buttons for non-actionable elements, such as decorative graphics or text.

Don't use ambiguous or unclear labels for buttons, as it can lead to confusion for users.

Don't use too many buttons on a page or in a single section, as it can overwhelm users and reduce usability.

Don't use primary and secondary buttons interchangeably, as it can confuse users and reduce the clarity of your interface.

Don't use disabled buttons without providing context for why the button is disabled. This can lead to confusion and frustration for users.

Custom states#

🧪 Experimental: The button exposes its loading state as a CSS custom state, which can be targeted with the :state() pseudo-class. This is handy to conditionally override the exposed CSS variables (e.g. --p-button-bg and --p-button-fg) without having to duplicate the state logic in your application.

Custom state

Applied when

loading

loading is true

p-button:state(loading) {
  --p-button-bg: light-dark(#025b3f, #21eeae);
  --p-button-fg: light-dark(#21eeae, #025b3f);
}

Custom states are a progressive enhancement: browsers without support for CustomStateSet or the :state() pseudo-class simply ignore these rules, the button keeps working and falls back to its default styling. Be aware that custom states can't be expressed during server side rendering, they are only applied once the component is hydrated on the client. Therefore, don't rely on :state() for styling that has to be correct on first paint.

For all other states and variants, use native CSS selectors instead:

Styling target

Selector

Disabled

p-button:disabled (the button is form-associated)

Hover

p-button:not(:disabled, :state(loading)):hover

Focus

p-button:focus-visible

Variant

a custom class, e.g. <p-button class="my-button" variant="secondary">

Since the button is a form-associated custom element, it is matched by the native :disabled pseudo-class as soon as the disabled attribute is set — no custom state is needed for it.

p-button {
  --p-button-bg: light-dark(#025b3f, #21eeae);
  --p-button-fg: light-dark(#21eeae, #025b3f);
}

p-button:not(:disabled, :state(loading)):hover {
  --p-button-bg: light-dark(#013d2a, #6ef7cf);
  --p-button-fg: light-dark(#6ef7cf, #013d2a);
}

p-button:disabled {
  --p-button-bg: light-dark(#6f3d0b, #ffaa4f);
  --p-button-fg: light-dark(#ffaa4f, #6f3d0b);
}

As with all color customizations, you are responsible for ensuring sufficient contrast and brand compliance.

Links