Skip to content

Latest commit

 

History

History
171 lines (118 loc) · 11.2 KB

README.md

File metadata and controls

171 lines (118 loc) · 11.2 KB

Buttons

Buttons allow users to trigger actions.

Guidelines

Web Components Usage

1. Installation

Install the Astro UXDS Button package via Command Line (Preferred Method)

npm i --save @astrouxds/rux-button

You may use Yarn, NPM, or your Node package manager of choice. The --save flag adds this component as a dependency in your package.json file.

Alternatively, download the Astro UXDS Component Library source to your project.

Via CLI:

git clone https://github.com/RocketCommunicationsInc/astro-components.git

Or, download the Astro UXDS Components as a .zip

2. Import the Astro Button Web Component

This example assumes you're using the NPM package in node_modules. Otherwise, import the component using the path to the Astro Components directory in your project.

import { RuxButton } from '@astrouxds/rux-button/rux-button.js'

3. Render the Astro Button Web Component

Pass properties as attributes of the Astro Button custom element:

<rux-button size="large" disabled secondary>
  Large disabled secondary button
</rux-button>

The component auto-imports the default Astro Icon Web Component for icons, if you specify one:

<rux-button icon="settings">
  Button with icon using astro UXDS icon web component
</rux-button>

Also, you can use Slots to define icons within buttons. This method is best if you need to override the default icon library SVG file:

  <rux-button>
    <rux-icon icon="custom" library="/icons/custom.svg" viewBox="0 0 128 128"></rux-icon>
    Slotted icon button
  </rux-button>

In this situation, you do not need to specify a size for the icon component -- the button's size attribute will define the appropriate size of the icon.

Properties

Property Type Default Required Description
disabled Boolean false No Disables the button via HTML disabled attribute. Icon takes on a distinct visual state. Cursor uses the not-allowed system replacement and all keyboard and mouse events are ignored.
secondary Boolean false No Displays a secondary button visual treatment suitable for secondary actions, such as a non-preferred alternative to an action identified by a primary button. For example, use a secondary button for the less preferred option in Ok/Cancel button pairings.
iconOnly Boolean false No Visually hides all text on the button, suitable for use cases where space is at a premium and the button intent is unambiguous, like a Play/Pause button. Requires the icon attribute to be set as well.
icon String '' No Displays an Astro icon matching this string to the left of the button text. For a full list of available icons, see the Icons section in Astro UXDS Guidelines. Required when the iconOnly attribute is true. Note that you can also use the Slot to add an icon.
size String '' No Displays the button as a 'small' or 'large' variant.

Basic HTML Usage

1. Include the Astro UXDS CSS file

Latest release is available in the static css directory.

<link rel="stylesheet" href="/your-project/path/astro.css" />

2. Markup the component using HTML and the Astro CSS classes

Astro CSS classes follow the BEM-style naming convention.

Configure the component using native HTML attributes or BEM-style class suffixes after rux-button--.

<button class="rux-button">Submit</button>

<button class="rux-button rux-button--large rux-button--secondary" disabled>
  Large disabled secondary button
</button>

The basic HTML/CSS usage supports icons if using Web Components (and importing the Astro Icon Component):

<button class="rux-button rux-button--icon">
  <rux-icon class="rux-icon rux-button__icon" icon="settings" color="white"></rux-icon>
  Button with icon using astro UXDS icon web component
</button>

Otherwise, wrap your icon SVG in an HTML element with the BEM-style classes "rux-icon rux-button__icon":

<button class="rux-button rux-button--icon">
  <div class="rux-icon rux-button__icon">
    <svg ... ></svg>
  </div>
  Button with local icon
</button>

Attributes

Attribute Type Default Required Description
disabled Boolean false No Disables the button via HTML disabled attribute. Icon takes on a distinct visual state. Cursor uses the not-allowed system replacement and all keyboard and mouse events are ignored.
secondary Boolean false No Displays a secondary button visual treatment suitable for secondary actions, such as a non-preferred alternative to an action identified by a primary button. For example, use a secondary button for the less preferred option in Ok/Cancel button pairings.
rux-button--icon-only Class — No Visually hides all text on the button, suitable for use cases where space is at a premium and the button intent is unambiguous, like a Play/Pause button. Must be used with the rux-button--icon class.
rux-button--icon Class — No Displays an Astro icon matching this string to the left of the button text. Required when element also has the class rux-button--icon-only. For a full list of available icons, see the Icons section in Astro UXDS Guidelines Note: Astro UXDS icons are only available when using the Web Component usage pattern, which imports the <rux-icon> component.
rux-button--size Class — No Displays the button as a 'small' or 'large' variant.

For more information about AstroUXDS usage outside of a Web Component environment, please see Astro UXDS Stylesheets

Revision History

4.1
  • Add styles for and example of using slots for Icon child component
4.0
  • Swapped kebab-cased icon-only attribute for standard camelCase iconOnly
  • Deprecated type attribute in favor of separate size, iconOnly, and secondary attributes. default type is No longer supported.
  • Fixed the width of the small icon-only button and ensured icon-only buttons show No text, even if text is provided
  • Fixed secondary button icon color
  • Re-enabled missing focus styles on buttons.
  • Removed undocumented critical button style.
  • Replaced Polymer 3 implementation with LitElement for improved speed and interoperability with JS Frameworks as well as simpler template declaration now available in vanilla JavaScript.
3.0
  • Removed Master Off Button Style
  • Replaced various properties with css custom properties to support
  • Removed .satcom class definition
  • Removed narrow/short definitions
1.4
  • Added rux_ prefixes and BEM-compatible classes to all satcom_-prefixed elements. NOTE: satcom_ will be removed in a future version
  • Disabled user selection of text on all buttons
  • Removed redundant background hover from disabled state by using :not() on the :hover state
  • Removed redundant background hover from master off by using :not() on the :hover state // deprecate after 1.4
  • Fixed Firefox alignment issue where text was misaligned vertically
  • Renamed half-height to short and half-width to narrow (Note: rux_ only, satcom_ retains old syntax)
  • Removed user-select and placed it in astro.css to apply to all input types
  • Embedded master off icon and removed the additional states required to handle icons and gradient backgrounds