@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. 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, menu
variant	String	primary	Variant of the button, one of variants – primary, secondary, outline, ghost, destructive, destructive-ghost, inverse, ghost-inverse or 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

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>

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