@justeattakeaway/pie-button

Table of Contents

1. Introduction
2. Installation
3. Importing the component
4. Peer Dependencies
5. Local Development
6. Props
7. Events
   • HTML example
   • Vue example (using Nuxt 3)
   • React example (using Next 13)
8. Forms usage
9. Testing
   • Browser Tests
   • Visual Tests

pie-button

pie-button is a Web Component built using the Lit library. It offers a simple and accessible button component for web applications.

This component can be easily integrated into various frontend frameworks and customized through a set of properties.

Installation

To install pie-button in your application, run the following on your command line:

# npm
$ npm i @justeattakeaway/pie-button

# yarn
$ yarn add @justeattakeaway/pie-button

For full information on using PIE components as part of an application, check out the Getting Started Guide.

Importing the component

// Default – for Native JS Applications, Vue, Angular, Svelte etc.
import { PieButton } from '@justeattakeaway/pie-button';

// React
// For React, you will need to import our React specific component build
// Which wraps the web component using the @lit-labs/react package

// Note: When using the React version of the component, please make sure
// you also include React as a dependency in your project as well. See Peer Dependencies section.

import { PieButton } from '@justeattakeaway/pie-button/dist/react';

Peer Dependencies

[!IMPORTANT] When using pie-button, you will also need to include a couple of dependencies to ensure the component renders as expected. See the PIE Wiki for more information and how to include these in your application.

Local development

Install the dependencies. Note that this, and the following commands below, should be run from the root of the monorepo:

yarn

To build the pie-button package, run the following command:

yarn build --filter=pie-button

If you'd like to develop using the component storybook, then you should build the component in watch mode, and run storybook in a separate terminal tab:

yarn watch --filter=pie-button

# in a separate terminal tab, run
yarn dev --filter=pie-storybook

Props

Property	Type	Default	Description
size	String	medium	Size of the button, one of sizes – xsmall, small-expressive, small-productive, medium, large
type	String	submit	Type of the button, one of types – submit, button, reset. Read further on MDN
variant	String	primary	Variant of the button, one of variants – primary, secondary, outline, ghost, destructive, destructive-ghost, inverse, ghost-inverse, outline-inverse
disabled	Boolean	false	If true, disables the button.
isFullWidth	Boolean	false	If true, sets the button width to 100% of its container.
isLoading	Boolean	false	If true, displays a loading indicator inside the button.
iconPlacement	String	leading	Icon placements of the icon slot, if provided, one of iconPlacements - leading, trailing
name	String	undefined	The name of the button, to be submitted with form data. Read further on MDN
value	String	undefined	The value of the button, to be submitted with form data. Read further on MDN
formaction	String	undefined	Designates an alternative URL for form data submission. Read further on MDN
formenctype	String	undefined	Specifies the form data encoding type. Read further on MDN
formmethod	String	undefined	Sets the HTTP method for form data. Read further on MDN
formnovalidate	Boolean	undefined	Ensures the form is submitted without native HTML validation. Read further on MDN
formtarget	String	undefined	Dictates where to display the response after form submission. Read further on MDN

In your markup or JSX, you can then use these to set the properties for the pie-button component:

<!-- Native HTML -->
<pie-button size='medium' type='button' variant='primary'>Click me!</pie-button>

<!-- JSX -->
<PieButton size='medium' type='button' variant='primary'>Click me!</PieButton>

Slots

Slot	Description
Default slot	The default slot is used to pass text into the button component.
icon	Used to pass in an icon to the button component. The icon placement can be controlled via the iconPlacement prop and we recommend using pie-icons-webc for defining this icon, but this can also accept an SVG icon.

Using pie-icons-webc with pie-button icon slot

We recommend using pie-icons-webc when using the icon slot. Here is an example of how you would do this:

<!--
  Note that pie-button and the icon that you want to use will need to be imported as components into your application.
  See the `pie-icons-webc` README for more info on importing these icons.
-->
<pie-button>
    <icon-plus-circle slot="icon"></icon-plus-circle>
    Search
</pie-button>

Events

This component does not use any custom event handlers. In order to add event listening to this component, you can treat it like a native HTML element in your application.

For example, to add a click handler in various templates:

HTML

<!-- Other attributes omitted for clarity -->
<pie-button onclick="e => console.log(e)">Click me!</pie-button>

Vue templates (using Nuxt 3)

<!-- Other attributes omitted for clarity -->
<pie-button @click="handleClick">Click me!</pie-button>

React templates (using Next 13)

<!-- Other attributes omitted for clarity -->
<PieButton onClick={handleClick}>increment</PieButton>

Forms usage

The pie-button web component is designed to integrate with standard HTML forms just like a native HTML button. When positioned inside a form, the component will automatically associate itself, enabling it to directly interact with the form context.

Button Attributes

The pie-button provides a set of attributes to customize its behavior within forms:

• type: Determines the button's function. Set to submit for form submissions or reset to clear form fields.
• formaction: Designates an alternative URL for form data submission when this specific button is clicked.
• formenctype: Specifies the form data encoding type during submission via this button.
• formmethod: Sets the HTTP method (e.g., GET or POST) for form data when initiated by this button.
• formnovalidate: If present, ensures the form is submitted without validation checks.
• formtarget: Dictates where to display the response after form submission.

Please see the MDN docs for more information on these attributes.

Integration Example

<form action="/default-endpoint" method="post">
    <input type="text" name="username" required>
    <pie-button
        type="submit"
        formaction="/alternate-endpoint"
        formenctype="multipart/form-data"
        formmethod="post"
        formnovalidate
        formtarget="_blank">
        Submit
    </pie-button>
</form>

In this example:

• The pie-button, when clicked, will send the form data to /alternate-endpoint instead of the form's default /default-endpoint.
• It uses the multipart/form-data encoding type for form submission.
• The form will submit using the POST method.
• No validation will be performed during submission, thanks to formnovalidate.
• The form's submission response will be opened in a new browser tab/window because of the formtarget="_blank" attribute.

Testing

Browser tests

To run the browser tests, run the following command from the root of the monorepo:

yarn test:browsers --filter=pie-button

Visual tests

To run the visual regression tests, run the following command from the root of the monorepo:

yarn test:visual --filter=pie-button

Note: To run these locally, you will need to ensure that any environment variables required are set up on your machine to mirror those on CI (such as Percy tokens). How you achieve this will differ between operating systems.

Setup via bash

export PERCY_TOKEN_PIE_BUTTON=abcde

Setup via package.json

Under scripts test:visual replace the environment variable with the below:

PERCY_TOKEN_PIE_BUTTON=abcde