Segmented Button

The Segmented Button control consists of several button parts. It provides the possibility to switch between several pages by activating one button segment at a time. Each segment may contain a text or (and) an icon. You can set a desired set of options for button segments and specify what segment should be selected.

Related resources

• Get the widget by installing the @svar-ui/react-core package.
• Check Segmented Button API Reference to see the list of configuration properties and events.
• Explore the samples to visualize the available features.

Initialization

To create an instance of Segmented Button on a page, you need to complete two steps:

• import the component on a page:

App.jsx

import { Segmented } from "@svar-ui/react-core";

• use the <Segmented> component to initialize the control and specify an options set to provide content for the button's segments:

App.jsx

import { Segmented } from "@svar-ui/react-core";

const options = [
  { id: 1, label: "One"},
  { id: 2, label: "Two"},
  { id: 3, label: "Three"}
];

export default function App() {
  return <Segmented options={options} />;
}

Setting the content of segments

You can specify the content of segments by setting an array of options, each of which will correspond to a button segment. Use the options configuration property to cope with this task.

Each option presents an object with properties presented as key:value pairs. An object of the options array may have the following properties:

• label - the text of a button segment
• icon - the name of the icon to be used in a button segment
• title - the tooltip text that will appear on hovering the mouse cursor over a button segment

Below you'll find examples of the content you can specify for button segments.

Text content

The text of segments is specified via the value of the label property of an option:

import { Segmented } from "@svar-ui/react-core";

const optionsText = [
  { id: 1, label: "One" },
  { id: 2, label: "Two" },
  { id: 3, label: "Three"}
];

export default function App() {
  return <Segmented options={optionsText} />;
}

Icons content

The icon property of an option serves to provide a desired icon for a segment. The name of a default icon is formed as wxi-name:

import { Segmented } from "@svar-ui/react-core";

const optionsIcons = [
  { id: 1, icon: "wxi-view-sequential" },
  { id: 2, icon: "wxi-view-grid" },
  { id: 3, icon: "wxi-view-column" }
];

export default function App() {
  return <Segmented options={optionsIcons} />;
}

Get more information on usage of icons in SVAR buttons.

Combination of a text and an icon

You can easily combine both a text and an icon inside a segment by using both the label and the icon properties in the option's object:

import { Segmented } from "@svar-ui/react-core";

const options = [
  { id: 1, label: "One", icon: "wxi-view-sequential" },
  { id: 2, label: "Two", icon: "wxi-view-grid" },
  { id: 3, label: "Three", icon: "wxi-view-column" }
];

export default function App() {
  return <Segmented options={options} />;
}

Titles for segments

A title is a tooltip text that appears on hovering the mouse cursor over a button segment and may contain some extra information about it. To add a title for a segment, make use of the title property of an option. Each segment can have a title of its own, e.g.:

import { Segmented } from "@svar-ui/react-core";

const options = [
  { id: 1, label: "One", icon: "wxi-view-sequential", title: "Grid mode" },
  { id: 2, label: "Two", icon: "wxi-view-grid", title: "Tiles mode" },
  { id: 3, label: "Three", icon: "wxi-view-column", title: "Two panels mode" }
];

export default function App() {
  return <Segmented options={options} value={1} />;
}

Related sample: Segmented Button

Setting the value

You can choose what segment should be selected in the Segmented Button with the help of the value property. As a value of this property, set the id of the corresponding option:

import { Segmented } from "@svar-ui/react-core";

const options = [
  { id: 1, label: "One", icon: "wxi-view-sequential" },
  { id: 2, label: "Two", icon: "wxi-view-grid" },
  { id: 3, label: "Three", icon: "wxi-view-column" }
];

export default function App() {
  return <Segmented options={options} value={2} />;
}

Related sample: Segmented Button

Getting the current value

It is possible to get the value of the segment selected at the moment. In React you do this by making the Segmented component controlled: store the selected value in state and update it via the onChange handler.

import { useState } from "react";
import { Segmented } from "@svar-ui/react-core";

const dataset = [
  { id: 1, label: "One"},
  { id: 2, label: "Two"},
  { id: 3, label: "Three"},
];

export default function App() {
  const [segment, setSegment] = useState(2);

  return (
    <Segmented
      options={dataset}
      value={segment}
      onChange={({ value }) => setSegment(value)}
    />
  );
}

After that the value assigned to the state variable will be updated on each change of the selected segment.

Related sample: Segmented Button

Catching the change of the selected segment

In case you need to catch the change of the selected segment, you can do it by handling the change event. In React this event is exposed as the camel-cased prop onChange. Inside the handler you can get the value of the newly selected segment in the following way:

function handleChange({ value }) {
  console.log(value);
  // => id of selected option
}

export default function App() {
  const options = [
    { id: 1, label: "One"},
    { id: 2, label: "Two"},
    { id: 3, label: "Three"},
  ];

  return <Segmented options={options} onChange={handleChange} />;
}

The handler function of the change event receives an object containing the id of the newly selected segment in its value field: onChange={({ value }) => ... }.

Customizing the content of segments

Text content

You can use a children-as-function template that receives the current option. In the example below, the text of the "color" property is used for segments:

import { Segmented } from "@svar-ui/react-core";

const optionsText = [
  { id: 1, label: "One", color: "Blue" },
  { id: 2, label: "Two", color: "Yellow"},
  { id: 3, label: "Three", color: "Green"}
];

export default function App() {
  return (
    <Segmented options={optionsText}>
      {(option) => <>{option.color}</>}
    </Segmented>
  );
}

Icons content

You can customize the appearance of the icons by applying the necessary style attributes via the icon CSS class and passing a children-as-function to render the "icon" field of an option:

import { Segmented } from "@svar-ui/react-core";

const optionsIcons = [
  { id: 1, icon: "wxi-view-sequential" },
  { id: 2, icon: "wxi-view-grid" },
  { id: 3, icon: "wxi-view-column" }
];

export default function App() {
  return (
    <Segmented options={optionsIcons}>
      {(option) => <i className={`icon ${option.icon}`} />}
    </Segmented>
  );
}

CSS:

.icon {
  height: 48px;
  font-size: 48px;
  line-height: 1;
  color: inherit;
}

HTML content

If you need use a more complex content in segments of the Segmented Button, you may add some HTML markup by returning it from the children-as-function.

For example, you can place a text under an icon. For this, wrap the template with the content of a segment in a <div> and use a CSS class that will specify the arrangement of elements in that div:

import { Segmented } from "@svar-ui/react-core";

const options = [
  { id: 1, label: "One", icon: "wxi-view-sequential" },
  { id: 2, label: "Two", icon: "wxi-view-grid" },
  { id: 3, label: "Three", icon: "wxi-view-column" }
];

export default function App() {
  return (
    <Segmented options={options}>
      {(option) => (
        <div>
          <i className={`icon ${option.icon}`} />
          <span className="bottom">{option.label}</span>
        </div>
      )}
    </Segmented>
  );
}

CSS:

.icon {
  height: 48px;
  font-size: 48px;
  line-height: 1;
  color: inherit;
}
.bottom {
  display: block;
  text-align: center;
}

In the above example, the templates for an icon and a text are wrapped in a div and the "bottom" CSS class defines the position of the text relative to the icon.

Related sample: Segmented Button

Styling the Segmented button

You can apply custom styling to the segments to get the desired look and feel. For this, specify the necessary CSS rules in your stylesheet and set the name of the custom class as a value of the css property in the component tag.

import { useState } from "react";
import { Segmented } from "@svar-ui/react-core";

const optionsText = [
  { id: 1, label: "One" },
  { id: 2, label: "Two" },
  { id: 3, label: "Three" }
];

export default function App() {
  const [value, setValue] = useState(2);

  return (
    <div className="demo-box">
      <Segmented
        css="my"
        options={optionsText}
        value={value}
        onChange={({ value }) => setValue(value)}
      />
    </div>
  );
}

CSS:

/* styling segments of the control */
.demo-box .my button {
  background-color: lightsalmon;
  color: white;
}

In the example the selector targets the element with the my class that the Segmented component applies (as configured by the css prop). The selector is written to be specific to the button segments.

Styling the selected segment

To change the style of the selected segment, add the .selected selector to the button element and provide new style attributes for it, like this:

/* styling the selected segment */
.demo-box .my button.selected {
  background-color: blueviolet;
  color: white;
}

The result of applying a custom style is the following: