Skip to content

Latest commit

 

History

History
158 lines (110 loc) · 10.1 KB

README.md

File metadata and controls

158 lines (110 loc) · 10.1 KB

Segmented Button

Segmented Buttons allow users to select one item at a time from two to four options. Selecting one option automatically turns off the last selection made. Segmented Buttons are mutually exclusive.

Guidelines

Web Components Usage

1. Installation

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

npm i --save @astrouxds/rux-segmented-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 Segmented 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 { RuxSegmentedButton } from '@astrouxds/rux-segmented-button/rux-segmented-button.js'

3. Render the Astro Segmented Button Web Component

Pass an Array of segments via the data attribute on the Segmented Button custom element. Segment items in the data Array must be objects with a label string. The first item in the Array will be auto-selected unless another segment item has a selected property with a truthy value:

import { RuxSegmentedButton } from '@astrouxds/rux-segmented-button/rux-segmented-button.js';

const myButtonSegments = [
  { label: "First segment" },
  { label: "Second segment" },
  { label: "Third segment" }
];

// ...

render() {
	return `<rux-segmented-button data="${myButtonSegments}" selected="${myButtonSegments[1].label}"></rux-segmented-button>`;
}

Properties (for the Segmented Button component)

Property Type Default Required Description
data Array [] Yes Items in this Array are the individual button segments.
selected String — No When passed in on load, this selects the first button segment with a matching label. When the selected segment changes, this property updates with the currently selected value, which reflects back to the component attribute. If no button segment label matches this string, then no segment is selected. This value takes priority over setting selected boolean property on the items in the data array.

Sample Astro UXDS Segmented Button data Array

;[
    { label: 'First segment' },
    { label: 'Second segment' },
    { label: 'Third segment' },
]

Properties for items within the data Array

Property Type Default Required Description
label String — Yes Defines the label for the button segment.
selected Boolean — No If true, selects this segment rather than the first segment in the data Array on mount. If more than one segment has a truthy selected value, the earliest one in the Array will register and the rest are ignored. Note that if the selected string property of the parent rux-segmented-button takes priority. When the selected segment changes within the component, this property updates with true or false if selected or not selected, on each segment.

Events

Event Name Description
change Fires when a button segment is changed. Inspect the Event target to find the data and selected component properties. See HTMLElement change event on MDN for more information. 
document.addEventListener('change', (e) =>
    console.log('Target element:', e.target)
)
// > Target element: <rux-segmented-button>

document.addEventListener('change', (e) =>
    console.log('Selected Segment:', e.target.selected)
)
// > Selected Segment: Second Segment

document.addEventListener('change', (e) =>
    console.log('Array of Segments:', e.target.data)
)
// > Array of Segments: [{ label: "First Segment", selected: false }, { label: "Second Segment", selected: true }, { label: "Third Segment", selected: false }]

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. Using Astro's CSS classes rux-segmented-button, rux-segmented-button__segment, compose your segmented button using styled HTML radio input elements.

Configure the component using native HTML attributes. For each group of radio buttons, the input elements representing choices must have the same value for their name attributes. Each <input> needs unique a id that matches the for attribute of a <label>.

<ul class="rux-segmented-button">
  <li class="rux-segmented-button__segment">
    <input type="radio" id="segment1" name="rux-group" />
    <label for="segment1">Segment 1</label>
  </li>
  <li class="rux-segmented-button__segment">
    <input type="radio" id="segment2" name="rux-group" />
    <label for="segment2">Segment 2</label>
  </li>
  <li class="rux-segmented-button__segment">
    <input type="radio" id="segment3" name="rux-group" />
    <label for="segment3">Segment 3</label>
  </li>
</ul>

Attributes

Attribute Type Default Required Description
selected Boolean false No If present on the <input> element, selects this segment rather than the first radio input element in the group.
name String — Yes Associates a group of Radio Button choices. All <input> elements in the group must have identical name values.
required Boolean false No Follows native form element required behavior, preventing submission of the form until a valid value has been entered.

Revision History

4.1
  • Exposed selected attribute on component to reflect currently selected segment to an attribute on the component
  • Added change event to notify document of segment selection change within component
4.0
  • 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.