@material/segmented-button

v14.0.0

The Material Components for the web segmented button component For more information about how to use this package see README

Latest version published 3 years ago

License: MIT

NPM

GitHub

Package Health Score

85 / 100

security
No known security issues
popularity
Influential project
maintenance
Sustainable
community
Active

Explore Similar Packages

Security

No known security issues

All security vulnerabilities belong to production dependencies of direct and indirect packages.

Security and license risk for significant versions

All Versions

Version			Vulnerabilities	License Risk
14.0.0	\|	04/2022	0 C 0 H 0 M 0 L	0 H 0 M 0 L
13.0.0	\|	09/2021	0 C 0 H 0 M 0 L	0 H 0 M 0 L
12.0.0	\|	07/2021	0 C 0 H 0 M 0 L	0 H 0 M 0 L
11.0.0	\|	04/2021	0 C 0 H 0 M 0 L	0 H 0 M 0 L
10.0.0	\|	02/2021	0 C 0 H 0 M 0 L	0 H 0 M 0 L

License

MIT

Security Policy

Is your project affected by vulnerabilities?

Scan your projects for vulnerabilities. Fix quickly with automated fixes. Get started with Snyk for free.

Get started free

Popularity

Influential project

Weekly Downloads (706,554)

GitHub Stars: 17.14K
Forks: 2.14K
Contributors: 380

Direct Usage Popularity

The npm package @material/segmented-button receives a total of 706,554 downloads a week. As such, we scored @material/segmented-button popularity level to be Influential project.

Based on project statistics from the GitHub repository for the npm package @material/segmented-button, we found that it has been starred 17,141 times.

Downloads are calculated as moving averages for a period of the last 12 months, excluding weekends and known missing data points.

Community

Active

Readme.md: Yes
Contributing.md: Yes
Code of Conduct: Yes
Contributors: 380
Funding: No

A good and healthy external contribution signal for @material/segmented-button project, which invites more than one hundred open source maintainers to collaborate on the repository.

Embed Package Health Score Badge

Maintenance

Sustainable

Commit Frequency

Open Issues: 402
Open PR: 109
Last Release: 3 years ago
Last Commit: 8 days ago

Further analysis of the maintenance status of @material/segmented-button based on released npm versions cadence, the repository activity, and other data points determined that its maintenance is Sustainable.

An important project maintenance signal to consider for @material/segmented-button is that it hasn't seen any new versions released to npm in the past 12 months, and could be considered as a discontinued project, or that which receives low attention from its maintainers.

As a healthy sign for on-going project maintenance, we found that the GitHub repository had at least 1 pull request or issue interacted with by the community.

Keep your project healthy

Check your package.json

Ensure all the packages you're using are healthy and well-maintained

Snyk Vulnerability Scanner

Get health score & security insights directly in your IDE

Package

Node.js Compatibility: not defined

Age: 4 years
Dependencies: 8 Direct
Versions: 1.2K
Install Size: 571 kB
Dist-tags: 3
# of Files: 53
Maintainers: 14
TS Typings: No

@material/segmented-button has more than a single and default latest tag published for the npm package. This means, there may be other tags available for this package, such as next to indicate future releases, or stable to indicate stable releases.

Readme

Segmented Buttons

Segmented buttons allow users to toggle the selected states of grouped buttons.

Using segmented buttons

Installation

npm install @material/segmented-button

Basic Usage

HTML Structure

<div role="group" class="mdc-segmented-button">
  <button aria-pressed="false" class="mdc-segmented-button__segment">
    <i class="material-icons mdc-segmented-button__icon">favorite</i>
  </button>
  <button aria-pressed="false" class="mdc-segmented-button__segment">
    <div class="mdc-segmented-button__label">Sample Text</div>
  </button>
  <button aria-pressed="false" class="mdc-segmented-button__segment">
    <i class="material-icons mdc-segmented-button__icon">favorite</i>
    <div class="mdc-segmented-button__label">Sample Text</div>
  </button>
</div>

Styles

@use '@material/ripple/common';
@use '@material/segmented-button/styles';

JavaScript Instantiation

import {MDCSegmentedButton} from '@material/segmented-button';
const segmentedButtonEl = document.querySelector('.mdc-segmented-button');
const segmentedButton = new MDCSegmentedButton(segmentedButtonEl);

> See Importing the JS component for more information on how to import JavaScript.

The MDC Segmented Button component automatically instantiates the child MDC Segmented Button Segment components.

Icons

We recommend using Material Icons from Google Fonts:

However, you can also use SVG, FontAwesome, or any other icon library you wish.

Segmented Button

Multi select

By default, the segmented button allows any number of segments to be selected at a time so that each segment is independent from the rest.

For accessibility, the segments are treated as toggle buttons. The segmented button is assigned role="group" and each segment has the attribute aria-pressed with a boolean value corresponding to its selected state.

<div role="group" class="mdc-segmented-button">
  <button aria-pressed="false" class="mdc-segmented-button__segment">
    <i class="material-icons mdc-segmented-button__icon">favorite</i>
  </button>
  <button aria-pressed="false" class="mdc-segmented-button__segment">
    <div class="mdc-segmented-button__label">Sample Text</div>
  </button>
  <button aria-pressed="false" class="mdc-segmented-button__segment">
    <i class="material-icons mdc-segmented-button__icon">favorite</i>
    <div class="mdc-segmented-button__label">Sample Text</div>
  </button>
</div>

Single select

The segmented button can be limited to select only one segment at a time. In this case, the selected segment cannot be unselected with a click. Selecting a different segment will unselect the previously selected segment. To make the segmented button single select, add the class mdc-segmented-button--single-select.

For accessibility, the segments are treated as radio buttons. The segmented button is assigned role="radiogroup" and each segment is assigned role="radio" and has the attribute aria-checked with a boolean value corresponding to its selected state.

<div role="radiogroup" class="mdc-segmented-button mdc-segmented-button--single-select">
  <button aria-checked="false" role="radio" class="mdc-segmented-button__segment">
    <i class="material-icons mdc-segmented-button__icon">favorite</i>
  </button>
  <button aria-checked="false" role="radio" class="mdc-segmented-button__segment">
    <div class="mdc-segmented-button__label">Sample Text</div>
  </button>
  <button aria-checked="false" role="radio" class="mdc-segmented-button__segment">
    <i class="material-icons mdc-segmented-button__icon">favorite</i>
    <div class="mdc-segmented-button__label">Sample Text</div>
  </button>
</div>

Segment

The segment is assumed to be a child of a segmented button. The segment can be in a selected or unselected state and changes state if the button is clicked or if the segmented button tells it to change its state. If the parent segmented button is single select and the segment is selected, the segment will not become unselected if it is clicked.

The segment can contain an icon, text, or both. If both an icon and text are used, the icon is assumed to come first (unless the page is loaded as rtl). Ripple effects and touch support can also be added.

Segment with text

To insert text inside of a segment, add the class mdc-segmented-button__label.

<button class="mdc-segmented-button__segment">
  <div class="mdc-segmented-button__label">Sample Text</div>
</button>

Segment with an icon

To insert an icon inside of a segment, add the class mdc-segmented-button__icon.

<button class="mdc-segmented-button__segment">
  <i class="material-icons mdc-segmented-button__icon">favorite</i>
</button>

Selected segment

The segment will remain in a visually toggled state while selected. To select the segment by default, add the class mdc-segmented-button__segment--selected and set the attribute aria-pressed or aria-checked (if the segmented button is multi or single select, respectively) to true.

<button aria-pressed="true" class="mdc-segmented-button__segment mdc-segmented-button__segment--selected">
  <div class="mdc-segmented-button__label">Sample Text</div>
</button>

Additional Information

Touch accessibility

Material Design spec advises that touch targets should be at least 48 x 48 px. To meet this requirement, add the following to your segments:

<div class="mdc-touch-target-wrapper">
  <button class="mdc-segmented-button__segment mdc-segmented-button--touch">
    <div class="mdc-segmented-button__touch"></div>
    <div class="mdc-segmented-button__label">Sample Text</div>
  </button>
</div>

Ripple

To include ripple effects when a segment is clicked add the following classes to the segment:

<button class="mdc-segmented-button__segment">
  <div class="mdc-segmented-button__ripple"></div>
  <div class="mdc-segmented-button__label">Sample Text</div>
</button>

Keyboard navigation

Each segment within the segmented button is a tabbable element. Arrow key navigation between segments is not supported at this time.

Style Customization

CSS Classes

CSS Class	Description
`mdc-segmented-button`	Mandatory. Indicates the wrapper for child segments.
`mdc-segmented-button__single-select`	Optional. Indicates the segmented button only allows one segment to be selected at a time.
`mdc-segmented-button__segment`	Mandatory. Indicates a button element that can be selected.
`mdc-segmented-button__icon`	Optional. Indicates an icon in the segment. We recommend using Material Icons from Google Fonts.
`mdc-segmented-button__label`	Optional. Indicates text in the segment.
`mdc-segmented-button__segment--selected`	Optional. Indicates that the segment is selected.
`mdc-touch-target-wrapper`	Optional. Indicates contained segment has touch target support.
`mdc-segmented-button--touch`	Optional. Indicates the segment has touch target support.
`mdc-segmented-button__touch`	Optional. Indicates the segment has touch target support.
`mdc-segmented-button__ripple`	Optional. Indicates the segment has a ripple effect when clicked.

> NOTE: Every segment element must contain an icon with class mdc-segmented-button__icon, text with class mdc-segmented-button__label, or both.

> NOTE: While mdc-touch-target-wrapper, mdc-segmented-button--touch, and mdc-segmented-button__touch are optional, if one is used then all three must be used.

Sass Mixins

Mixin	Description
`outline-color`	Customizes the border color around each segment.
`unselected-ink-color`	Customizes the text and icon ink color for an unselected segment.
`unselected-container-fill-color`	Customizes the background color for an unselected segment.
`selected-ink-color`	Customizes the text and icon ink color for a selected segment.
`selected-container-fill-color`	Customizes the background color for an selected segment.

`MDCSegmentedButton`, `MDCSegmentedButtonSegment`, and `SegmentDetail` Properties and Methods

The MDC Segmented Button package is composed of two JavaScript classes:

MDCSegmentedButton defines the behavior of a set of segments.
MDCSegmentedButtonSegment defines the behavior of a single segment.

To use the MDCSegmentedButton and MDCSegmentedButtonSegment classes, import both from @material/segmented-button.

`SegmentDetail`

The SegmentDetail type contains only the actionable information about a specific MDCSegmentedButtonSegment.

Property	Value Type	Description
`index`	`number`	The index of the segment.
`selected`	`boolean`	The segment's selected state.
`segmentId?`	`string \| undefined`	The segment's segmentId, if provided.

`MDCSegmentedButton`

Method Signature	Description
`getSelectedSegments() => readonly SegmentDetail[]`	Proxies to foundation's `getSelectedSegments` method.
`selectSegment(indexOrSegmentId: number \| string) => void`	Proxies to foundation's `selectSegment` method.
`unselectSegment(indexOrSegmentId: number \| string) => void`	Proxies to foundation's `unselectSegment` method.
`isSegmentSelected(indexOrSegmentId: number \| string) => boolean`	Proxies to foundation's `isSegmentSelected` method.

Property	Value Type	Description
`segments`	`ReadOnlyArray`	Array of child `MDCSegmentedButtonSegment`s.
`ripple`	`MDCRipple` (read-only)	The `MDCRipple` instance for the root element that `MDCSegmentedButton` initializes.

Events

Event Name	`event.detail`	Description
MDCSegmentedButton:change	`SegmentDetail`	Indicates that a segment's selected value may have changed due to a click.

`MDCSegmentedButtonSegment`

Method Signature	Description
`setIndex(index: number) => void`	Sets segment's index.
`setIsSingleSelect(isSingleSelect: boolean) => void`	Sets segment's isSingleSelect.
`isSelected() => boolean`	Proxies to foundation's `isSelected` method.
`setSelected() => void`	Proxies to foundation's `setSelected` method.
`setUnselected() => void`	Proxies to foundation's `setUnselected` method.
`getSegmentId() => string \| undefined`	Proxies to foundation's `getSegmentId` method.

Events

Event Name	`event.detail`	Description
`MDCSegmentedButtonSegment:selected`	`SegmentDetail`	Indicates the segment's selected status just changed due to a click.

Usage within Web Frameworks

If you are using a JavaScript framework, such as React or Angular, you can create Segmented Buttons for your framework. Depending on your needs, you can use the Simple Approach: Wrapping MDC Web Vanilla Components, or the Advanced Approach: Using Foundations and Adapters. Please follow the instructions here.

Adapters: `MDCSegmentedButtonAdapter` and `MDCSegmentedButtonSegmentAdapter`

See segmented-button/component.ts and segment/component.ts for vanilla DOM implementations of these adapter APIs for reference.

`MDCSegmentedButtonAdapter`

Method Signature	Description
`hasClass(className: string) => boolean`	Returns true if segmented button has className, otherwise returns false.
`getSegments() => readonly SegmentDetail[]`	Returns child segments represented as a readonly list of SegmentDetails.
`selectSegment(indexOrSegmentId: number \| string) => void`	Sets identified segment to be selected.
`unselectSegment(indexOrSegmentId: number \| string) => void`	Set identified segment to be not selected.
`notifySelectedChange(detail: SegmentDetail) => void`	Notifies the client about the changed segment with a `change` event.

>NOTE: notifySelectedChange must pass along a SegmentDetail representing the potentially changed Segment, and must be observable by the client (e.g. via DOM event bubbling).

`MDCSegmentedButtonSegmentAdapter`

Method Signature	Description
`isSingleSelect() => boolean`	Returns true if wrapping segmented button is single select, otherwise returns false.
`getAttr(attrName: string) => string \| null`	Returns root element's attribute if it is set, otherwise returns null.
`setAttr(attrName: string, value: string) => void`	Sets root element's attribute value to `value`.
`addClass(className: string) => void`	Adds class to the root element.
`removeClass(className: string) => void`	Removes class from the root element.
`hasClass(className: string) => boolean`	Returns true if root element has class, otherwise returns false.
`notifySelectedChange(selected: boolean) => void`	Notifies the Segmented Button that the segment's selected state has changed.

>NOTE: notifySelectedChange must pass along a SegmentDetail representing the Segment, and must be observable by the mdc-segmented-button element (e.g. via DOM event bubbling).

Foundations: `MDCSegmentedButtonFoundation` and `MDCSegmentedButtonSegmentFoundation`

`MDCSegmentedButtonFoundation`

Method Signature	Description
`selectSegment(indexOrSegmentId: number \| string) => void`	Sets identified segment to be selected.
`unselectSegment(indexOrSegmentId: number \| string) => void`	Set identified segment to be not selected.
`getSelectedSegments() => readonly SegmentDetail[]`	Returns selected segments as readonly list of SegmentDetails.
`isSegmentSelected(indexOrSegmentId: number \| string) => boolean`	Returns true if identified segment is selected, otherwise returns false.
`isSingleSelect() => boolean`	Returns true if segmented button is single select, otherwise returns false.
`handleSelected(detail: SegmentDetail) => void`	Handles a `selected` event. Maintains single select restrictions, if applicable, and notifies client.

`MDCSegmentedButtonFoundation` Event Handlers

When wrapping the Segmented Button foundation, the following events must be bound to the indicated foundation methods:

Events	Element Selector	Foundation Handler
`MDCSegmentedButtonSegment:selected`	`.mdc-segmented-button` (root)	`handleSelected`

`MDCSegmentedButtonSegmentFoundation`

Method Signature	Description
`isSelected() => void`	Returns true if segment is currently selected.
`setSelected() => void`	Sets segment to be selected.
`setUnselected() => void`	Sets segment to be not selected.
`getSegmentId() => string \| undefined`	Returns segment's segmentId if it was provided, otherwise return undefined.
`handleClick() => void`	Handles a `click` event. Changes selected state if able (due to single select) and notifies Segmented Button.

`MDCSegmentedButtonSegmentFoundation` Event Handlers

When wrapping the Segment foundation, the following events must be bound to the indicated foundation methods:

Events	Element Selector	Foundation Handler
`click`	`.mdc-segmented-button__segment` (root)	`handleClick`

@material/segmented-button dependencies

tslib @material/base @material/theme @material/ripple @material/elevation @material/typography @material/touch-target @material/feature-targeting

FAQs

What is @material/segmented-button?

The Material Components for the web segmented button component. Visit Snyk Advisor to see a full health score report for @material/segmented-button, including popularity, security, maintenance & community analysis.

Is @material/segmented-button popular?

The npm package @material/segmented-button receives a total of 706,554 weekly downloads. As such, @material/segmented-button popularity was classified as an influential project. Visit the popularity section on Snyk Advisor to see the full health analysis.

Is @material/segmented-button well maintained?

We found indications that @material/segmented-button maintenance is sustainable demonstrating some project activity. We saw a total of 380 open source contributors collaborating on the project. See the full package health analysis to learn more about the package maintenance status.

Is @material/segmented-button safe to use?

The npm package @material/segmented-button was scanned for known vulnerabilities and missing license, and no issues were found. Thus the package was deemed as safe to use. See the full health analysis review.

Last updated on 21 December-2024, at 06:19 (UTC).

Build a secure application checklist

Select a recommended open source package

Minimize your risk by selecting secure & well maintained open source packages

DONE

Scan your app for vulnerabilities

Scan your application to find vulnerabilities in your: source code, open source dependencies, containers and configuration files

SCAN NOW

Fix identified vulnerabilities

Easily fix your code by leveraging automatically generated PRs

AUTO FIX

Monitor for new issues

New vulnerabilities are discovered every day. Get notified if your application is affected

MONITOR APP

Package Health Score

Explore Similar Packages

Security and license risk for significant versions

Is your project affected by vulnerabilities?

Weekly Downloads (706,554)

Direct Usage Popularity

Embed Package Health Score Badge

Commit Frequency

Keep your project healthy

Check your package.json

Snyk Vulnerability Scanner

Readme

Segmented Buttons

Using segmented buttons

Installation

Basic Usage

HTML Structure

Styles

JavaScript Instantiation

Icons

Segmented Button

Multi select

Single select

Segment

Segment with text

Segment with an icon

Selected segment

Additional Information

Touch accessibility

Ripple

Keyboard navigation

Style Customization

CSS Classes

Sass Mixins

MDCSegmentedButton, MDCSegmentedButtonSegment, and SegmentDetail Properties and Methods

SegmentDetail

MDCSegmentedButton

Events

MDCSegmentedButtonSegment

Events

Usage within Web Frameworks

Adapters: MDCSegmentedButtonAdapter and MDCSegmentedButtonSegmentAdapter

MDCSegmentedButtonAdapter

MDCSegmentedButtonSegmentAdapter

Foundations: MDCSegmentedButtonFoundation and MDCSegmentedButtonSegmentFoundation

MDCSegmentedButtonFoundation

MDCSegmentedButtonFoundation Event Handlers

MDCSegmentedButtonSegmentFoundation

MDCSegmentedButtonSegmentFoundation Event Handlers

@material/segmented-button dependencies

FAQs

What is @material/segmented-button?

Is @material/segmented-button popular?

Is @material/segmented-button well maintained?

Is @material/segmented-button safe to use?

Build a secure application checklist

Select a recommended open source package

Scan your app for vulnerabilities

Source Code

Open Source

Container

Config

Fix identified vulnerabilities

Monitor for new issues

`MDCSegmentedButton`, `MDCSegmentedButtonSegment`, and `SegmentDetail` Properties and Methods

`SegmentDetail`

`MDCSegmentedButton`

`MDCSegmentedButtonSegment`

Adapters: `MDCSegmentedButtonAdapter` and `MDCSegmentedButtonSegmentAdapter`

`MDCSegmentedButtonAdapter`

`MDCSegmentedButtonSegmentAdapter`

Foundations: `MDCSegmentedButtonFoundation` and `MDCSegmentedButtonSegmentFoundation`

`MDCSegmentedButtonFoundation`

`MDCSegmentedButtonFoundation` Event Handlers

`MDCSegmentedButtonSegmentFoundation`

`MDCSegmentedButtonSegmentFoundation` Event Handlers