Nonlinear Performance Magnification

    @bliss-design-system/button
    TypeScript icon, indicating that this package has built-in type declarations

    1.8.0 • Public • Published

    <bliss-button>

    <bliss-button> renders a button, or an anchor element styled as a button.

    📦 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 to have the <bliss-icon> component and the Iconsets registered to your application. Both are peer dependencies of this component, and you won't be able to see the icon without them.

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

    To use the button with a loading spinner, you'll need to have the <bliss-loading> component registered to your application. It is a peer dependency of this component, and you won't be able to see the loading state without it.

    <bliss-button 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>

    Attributes

    The button accepts the following attributes:

    Attribute Type Description Default Required Options
    size string defines the button size medium false small, medium
    type string defines the button type button false button, submit, reset
    theme string button theme default false default, neutral, critical
    variant string button variant primary false primary, secondary, ghost
    disabled boolean disable the button false false -
    loading boolean display the loading spinner false false -
    icon-only boolean display an icon only false false -
    icon-trailing boolean display icon after the label false false -
    full-width boolean make the button full width of its container false false -

    For a link styled like a button, you can use the following attributes in addition to the ones in the table above:

    Attribute Type Description Default Required Options
    href string URL '' false -
    target string where to display the linked URL '' false _blank, _self, _top, _parent
    rel string relationship of the linked URL '' false -
    download string download instead of navigate '' false -

    Styling

    The button comes with three themes to choose from, but we recognise that there might be instances where that might not be enough. If you need to change the color of the component, or of an icon or loading spinner within the component, you can access the styles with the ::part pseudo element. The implementation looks like this:

    bliss-button::part(button) {
      color: green
    }

    ⚠️ Please note, Bliss can't support all of the variations that might come up over time, so it will be your full responsibility to maintain any changes that you make to the component that don't follow the existing API.

    Accessibility

    The <bliss-button> handles labelling for you in every state.

    The only requirement is that you always pass in text content, even if you are using an icon-only variation of the button, because that is what the button relies on to populate its aria-label.

    The colour contrast is handled out of the box for each variant and each theme.

    🫕 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 bliss@bryter.io or via the #bliss_support Slack channel .

    Install

    npm i @bliss-design-system/button

    DownloadsWeekly Downloads

    19,254

    Version

    1.8.0

    License

    MIT

    Unpacked Size

    255 kB

    Total Files

    10

    Last publish

    Collaborators

    • bryter-bliss
    • coolcut
    • gvonkoss
    • kilmc