@bliss-design-system/button

<bliss-button>

<bliss-button> does excellent things.

• Installation
• Usage
  • Properties
• Contributing
  • Demoing with Storybook
  • Testing
  • Committing
  • Opening a merge request
• Troubleshooting

📦 Installation

To install this component, run:

yarn add @bliss-design-system/button

🏎 Usage

To use this component, you'll need to register the component to the window's Custom Elements Registry. In order to achieve that, you'll want to call this function within your application's client-facing entry file:

import { blissRegisterButton } from '@bliss-design-system/button';

blissRegisterButton(); // Registers <bliss-button>

That will make the component available in your application and you can use it like this:

<!-- renders a primary button with a default theme in medium size -->
<bliss-button>I am button</bliss-button>

To use the button with an icon, you'll need the <bliss-icon> component, and you can use it like this:

<bliss-button>
  <bliss-icon slot="icon" name="trash"></bliss-icon>
  Delete
</bliss-button>

To use the button with a loading spinner, you'll need the <bliss-loading> component, and you can use it like this:

<bliss-button>
  <bliss-loading slot="icon"></bliss-loading>
  Doing things
</bliss-button>

There are multiple attributes you can add to the button to leverage different needs, e.g. for a secondary, full width, critical button:

<bliss-button variant="secondary" theme="critical" full-width>
  Very wide and important button
</bliss-button>

In addition to the examples above, the you can also render an <a> with button styling (including the button attributes defined below), by providing a href:

<bliss-button href="www.example.com">
  I'm a link!
</bliss-button>

Properties

The component accepts the following properties:

Attribute	Type	Description	Default	Required	Options
size	string	defines the button size	medium	no	small, medium
type	string	defines the button type	button	no	button, submit, reset
theme	string	button theme	default	no	default, neutral, critical
variant	string	button variant	primary	no	primary, secondary, `ghost
disabled	boolean	disable the button	false	no	-
loading	boolean	display the loading spinner	false	no	-
icon-only	boolean	display an icon only	false	no	-
icon-trailing	boolean	display icon after the label	false	no	-
full-width	boolean	make the button full width of its container	false	no	-
Anchor specific attributes below
href	string	URL	''	no	-
target	string	where to display the linked URL	''	no	_blank, _self, _top, _parent
rel	string	relationship of the linked URL	''	no	-
download	string	download instead of navigate	''	no	-

🫕 Contributing

If you'd like to contribute, please open an issue with your suggested change on our Proposal Board. Once that is accepted, either the Bliss team will work on it or you can make changes locally by doing the following:

# Clone this repository
git clone https://gitlab.com/bliss-design-system/components.git

# Move into the component toolkit
cd components/

# Install the dependencies
yarn

You don't need to move into the package's directory to run storybook, tests or anything else. All of those commands exist in the root of the component toolkit, so while you can work on the component within its specific folder, you don't need to move through directories to run anything.

Demoing with Storybook

You can see all of your changes as you make them on Storybook.

To run a local instance of Storybook for this component, run:

yarn storybook

Testing

If you want to test as you develop, run:

yarn test

// or

yarn test:watch

Committing

We follow the Conventional Commits specification, meaning that you'll be prompted to fill out a descriptive message when you commit. We also use these commits to manage our releases, so we appreciate details.

As a guideline for this component, we use:

• fix for bug fixes, minor stylistic improvements, etc.
• feat for any backward compatible API changes.

For anything that breaks backwards compatibility or introduces significant changes that require a major version change, please get in touch with the team.

Opening a merge request

When you're ready to open a merge request, please use a descriptive title and fill out the provided template.

The team will be notified, but it helps to post your merge request in #bliss_support.

🙃 Troubleshooting

We'll fill this section out as we go and as issues are raised. But if you haven't found what you're looking for, get in touch via [e-mail] or via the #bliss_support Slack channel ✨.