button

A button to trigger an action when a user clicks on it.

  • XML element: button

  • Java class: JmixButton

Basics

A button can have a text, an icon, or both:

button 1

An example of defining a button with text, icon and a tooltip (title attribute) retrieved from the message bundle:

<button id="toolsButton"
        text="Tools"
        title="msg://toolsButton.title"
        icon="TOOLS"/>

To handle button clicks, subscribe to the ClickEvent in the view class:

@Subscribe(id = "toolsButton", subject = "clickListener")
public void onToolsButtonClick(final ClickEvent<JmixButton> event) {
    // ...
}

Action

Instead of creating a ClickEvent handler, you can associate the button with an existing Action. Using existing actions provides a more efficient approach, as it automatically updates various attributes and behavior of the button. This can include button’s state, visibility, text, title, icon, and user interaction outcome.

If the action is defined for the view, specify the action id in the button’s action attribute:

<actions>
    <action id="helloAction" text="Say Hello"/>
</actions>
<layout>
    <button id="helloButton" action="helloAction"/>
</layout>

If the action is defined for a component, such as dataGrid, specify the component id and action id separated by the dot in the button’s action attribute:

<layout>
    <button id="createButton" action="usersTable.create"/>

    <dataGrid id="usersTable" dataContainer="users">
        <actions>
            <action id="create" type="list_create"/>
        </actions>
    </dataGrid>
</layout>

Variants

The themeNames attribute allows you to assign a specific button style from the set of predefined variants.

  • Importance variants:

    button variant 1
    <button text="Primary" themeNames="primary"/>
    <button text="Secondary"/>
    <button text="Tertiary" themeNames="tertiary"/>
  • Danger or error variants:

    button variant 2
    <button text="Primary" themeNames="primary error"/>
    <button text="Secondary" themeNames="error"/>
    <button text="Tertiary" themeNames="tertiary error"/>
  • Success variants:

    button variant 3
    <button text="Primary" themeNames="primary success"/>
    <button text="Secondary" themeNames="success"/>
    <button text="Tertiary" themeNames="tertiary success"/>
  • Contrast variants:

    button variant 4
    <button text="Primary" themeNames="primary contrast"/>
    <button text="Secondary" themeNames="contrast"/>
    <button text="Tertiary" themeNames="tertiary contrast"/>
  • Size variants:

    button variant 5
    <button text="Large" themeNames="large"/>
    <button text="Normal"/>
    <button text="Small" themeNames="small"/>
  • Inline variant without any white space around the button text:

    button variant 6
    <button text="Tertiary inline" themeNames="tertiary-inline"/>

The variant theme names are defined in the ButtonVariant class. See also Vaadin Docs for more information about button styles.

Attributes

disableOnClick

If the disableOnClick attribute is set to true, the button will be automatically disabled when clicked, typically to prevent (accidental) extra clicks on a button. You can later re-enable the button by invoking the setEnabled(true) method.

icon

Allows to set the Icon component for the button. There are two built-in icon sets:

  • Lumo Icons. You can set the Lumo icon in XML:

    <button id="lumoBtn" icon="lumo:photo"/>

    or in the controller class:

    @ViewComponent
    protected JmixButton lumoBtn;
    
    @Subscribe
    public void onInit(InitEvent event) {
        Icon lumoIcon = new Icon("lumo", "photo");
        lumoBtn.setIcon(lumoIcon);
    }
  • Vaadin Icons. The icons from this set have constants. You can set the Vaadin icon in XML:

    <button id="vaadinBtn" icon="ALARM"/>

    or in the controller class:

    @ViewComponent
    protected JmixButton vaadinBtn;
    
    @Subscribe
    public void onInit(InitEvent event) {
        Icon vaadinIcon = new Icon(VaadinIcon.PHONE);
        vaadinBtn.setIcon(vaadinIcon);
    }

Since button can have prefix and suffix components, external images can be used instead of icons.

  • image component as an icon:

    <button id="imageIconBtn" text="Image">
        <prefix>
            <image resource="icons/icon.png"
                   width="var(--lumo-icon-size-m)"/> (1)
    
        </prefix>
    </button>
    1 Set the same width as for VaadinIcon
    button icon image
  • svgIcon component as an icon:

    <button id="svgIconBtn" text="Svg Icon">
        <prefix>
            <svgIcon resource="icons/jmix-icon.svg"/>
        </prefix>
    </button>
    button icon svg

iconAfterText

If the iconAfterText attribute is set to true, this button’s icon should be positioned after it’s text content.

whiteSpace

MDN

Defines the component’s white-space style value. Possible values are:

  • NORMAL

  • NOWRAP

  • PRE

  • PRE_WRAP

  • PRE_LINE

  • BREAK_SPACES

  • INHERIT

  • INITIAL

Handlers

To generate a handler stub in Jmix Studio, use the Handlers tab of the Jmix UI inspector panel or the Generate Handler action available in the top panel of the view class and through the CodeGenerate menu (Alt+Insert / Cmd+N).

clickListener

Fires the com.vaadin.flow.component.ClickEvent with the click subject. It is triggered whenever the component is clicked.

For example:

@Subscribe(id = "clickBtn", subject = "clickListener") (1)
public void onClickBtnClick(final ClickEvent<JmixButton> event) {
    JmixButton button = event.getSource(); (2)
}
1 The @Subscribe annotation connects the handler method to the component by the component’s id.
2 If needed, you can get the clicked button from the event object.

To register the event handler programmatically, use the addClickListener() component method.

doubleClickListener

Fires the com.vaadin.flow.component.ClickEvent with the doubleClick subject. It is triggered when the user clicks the button twice within a short time interval.

For example:

@Subscribe(id = "clickBtn", subject = "doubleClickListener")
public void onClickBtnClick1(final ClickEvent<JmixButton> event) {
    notifications.show("This is doubleClickListener");
}

To register the event handler programmatically, use the addDoubleClickListener() component method.

singleClickListener

Fires the com.vaadin.flow.component.ClickEvent with the singleClick subject. The event is triggered after a timeout to ensure it is not a double-click.

For example:

@Subscribe(id = "clickBtn", subject = "singleClickListener")
public void onClickBtnClick2(final ClickEvent<JmixButton> event) {
    notifications.show("This is singleClickListener");
}

To register the event handler programmatically, use the addSingleClickListener() component method.

Elements

See Also

See Vaadin Docs for more information.