Skip to content

Toggle Button

A Vaadin Flow add-on that provides a two-state on/off toggle switch with customizable labels, icons, and theme variants.

Overview

Use the Toggle Button add-on when a standard checkbox feels too utilitarian for a boolean setting — enabling a feature flag, toggling dark mode, or controlling a user preference. The component integrates with Vaadin's HasValue so it works naturally with Binder and data binding.

Features

  • Toggle between two states with a single click.
  • Customizable left and right labels.
  • Icons on either side of the switch, with two layout options: icons outside labels (default), or icons inside adjacent to the switch track.
  • Optional label highlighting: the active side uses the theme variant color; the inactive side is dimmed.
  • Theme variants: SMALL, MEDIUM, LARGE, LONGSWIPE, PRIMARY, SUCCESS, WARNING, ERROR, CONTRAST.
  • LONGSWIPE variant produces a wider switch track, optimized for touch interaction; can be combined with size variants.
  • Fluent API for easy configuration.
  • Full integration with Vaadin's HasValue, HasSize, HasLabel, HasAriaLabel, and HasTooltip.

Supported versions

Refer to the Vaadin Directory page for exact version compatibility.

Installation

From the Vaadin Directory

Available in the Vaadin Directory.

Maven dependency

<dependency>
    <groupId>com.flowingcode.vaadin.addons</groupId>
    <artifactId>toggle-button-addon</artifactId>
    <version>X.Y.Z</version>
</dependency>

Replace X.Y.Z with the latest released version. Releases are available from Maven Central.

For snapshot builds, see maven.flowingcode.com/snapshots.

JavaDoc is published at javadoc.flowingcode.com.

Usage

Create a ToggleButton and optionally configure labels, icons, and theme variants:

// Basic toggle button
ToggleButton toggle = new ToggleButton();

// With a field label and initial value
ToggleButton toggle = new ToggleButton("Dark mode", true);

// With left/right labels
ToggleButton toggle = new ToggleButton()
    .setLeftLabel("Off")
    .setRightLabel("On");

// With icons
ToggleButton toggle = new ToggleButton()
    .setLeftLabel("Dark")
    .setRightLabel("Light")
    .setLeftIcon(new Icon(VaadinIcon.MOON))
    .setRightIcon(new Icon(VaadinIcon.SUN_O));

// Label highlighting: active side uses the theme variant color, inactive side is dimmed
ToggleButton toggle = new ToggleButton()
    .setLeftLabel("Off")
    .setRightLabel("On")
    .withHighlightLabel();

// Icons-inside layout: [label] [icon] [switch] [icon] [label]
ToggleButton toggle = new ToggleButton()
    .setLeftIcon(new Icon(VaadinIcon.MOON))
    .setLeftLabel("Dark")
    .setRightLabel("Light")
    .setRightIcon(new Icon(VaadinIcon.SUN_O))
    .withIconsInside();

// Apply theme variants
toggle.addThemeVariants(ToggleButtonVariant.PRIMARY);
toggle.addThemeVariants(ToggleButtonVariant.LONGSWIPE, ToggleButtonVariant.LARGE);

// Listen to value changes
toggle.addValueChangeListener(e ->
    Notification.show("Toggle is now: " + (e.getValue() ? "on" : "off")));

The component is HasValue<Boolean>, so it can be bound directly with Binder:

binder.forField(toggle).bind(MyBean::isEnabled, MyBean::setEnabled);

Special configuration when using Spring

By default, Vaadin Flow only scans com/vaadin/flow/component for UI components and views. To pick up the add-on's components when running on Spring, allow-list the com.flowingcode package in src/main/resources/application.properties:

vaadin.allowed-packages = com.vaadin,org.vaadin,dev.hilla,com.flowingcode

See the Spring package-scanning documentation for more details.

API reference

Headline types exposed by the add-on:

  • ToggleButton — the toggle switch component; implements HasValue<Boolean>, HasSize, HasLabel, HasAriaLabel, and HasTooltip.
  • ToggleButtonVariant — enum of theme variants (SMALL, MEDIUM, LARGE, LONGSWIPE, PRIMARY, SUCCESS, WARNING, ERROR, CONTRAST).

For the full API surface, browse the published JavaDoc.

Demo

A live demo is available at addonsv25.flowingcode.com/togglebutton. To run the demo locally:

git clone https://github.com/FlowingCode/ToggleButton.git
cd ToggleButton
mvn clean install jetty:run

Then open http://localhost:8080/.

Source code

ToggleButton on GitHub — distributed under Apache License 2.0.