Two State Button

The Two State Button control is a special button variation that has two states: unpressed and pressed. You can add a click handler for a button, change the button's state, provide separate content for the pressed and unpressed states, set an appropriate button's type and make a button disabled whenever you need it.

Related resources

• Get the widget by installing the @wx/svelte-core package.
• Check Two State Button API Reference to see the list of configuration properties.
• Explore the samples to visualize the available features.

Initialization

To create an instance of the Two State button on a page, you need to complete the following steps:

• import the source file of the control on a page:

App.svelte

<script>
    import { TwoState } from "@wx/svelte-core";
</script>

• use the <TwoState> tag to initialize the control:

App.svelte

<TwoState>Click Me</TwoState>

Setting the pressed state

By default, Two State button is initialized in the unpressed state. To enable the pressed state of the button, you should set the value property to true:

<TwoState value={true}>
    Click me
</TwoState>

Setting different content for each state

You can provide different content for the default (unpressed) and the pressed states of Two State button:

• For the unpressed state, specify the necessary control's properties in the TwoState tag.
• For the pressed state, place a span with the "active" slot inside the Two State tag. After that you can add some content into the span and it will be displayed when the button is pressed.

<TwoState {click}>
    Click Me
    <span slot="active">Working...</span>
</TwoState>

It is possible to use different icons for both states of the button. Read more in the Using icons section.

Related sample: Two State Button

Getting the current state

It is possible to get the current state of the Two State button. For this, you need:

• specify a variable that will contain the value of the button (it may contain the initial value):

<script>
    import { TwoState } from "@wx/svelte-core";

    let state = true;
</script>

• bind the variable to the value property of the control:

<TwoState bind:value={state} />

If the name of the variable matches its value, you can use the shorthand while binding the property:

<script>
    import { TwoState } from "@wx/svelte-core";

    let value = true;
</script>

<TwoState bind:value />

After that the value assigned to the bound variable will be updated on each change of the button's state.

Specifying the appearance of a button

You can specify the desired look and feel of a Two State button by setting the corresponding type. The type of the Two State button is defined by the type property.

<TwoState type={'primary'}>Click Me</TwoState>

The Two State Button control inherits its types from SVAR Button. The list below provides the available types of the Two State Button.

• 'default'

• 'primary'

• 'secondary'

• 'danger'

• 'link' (can have an icon and be disabled as well as a standard button)

Related sample: Two State Button

Using a button block

There is a special button type that you can use if you need a button to span the full width of its parent. It is called a button block and has two sub-types:

• 'primary block' (has the primary styling)

• 'secondary block' (has the secondary styling)

Related sample: Two State Button

Handling a button click

To add a click handler function to your button, make use of the click property.

You can declare it in two ways:

• specify the name of the function as a value of the click property:

<script>
    function myFunction() {
        // some custom logic
    };
</script> 

<TwoState click={myFunction}>Click Me</TwoState>

• use the {click} shorthand, if the name of the handler function matches the name of the property:

<script>
    function click() {
        // some custom logic
    };
</script>

<div>
    <TwoState {click}>Click Me</TwoState>
</div>

Showing a message on click

SVAR provides an extended messaging system to implement user-app communication. Since one of the most common cases for a button click is a call of a notice or a dialog box, you can use the library helpers to create a suitable message box while handling a Two State button click.

For example, you can use the showNotice() helper to display a message:

<script>
    import { TwoState } from "@wx/svelte-core";
    import { getContext } from "svelte";

    // getting the helper 
    const { showNotice } = getContext("wx-helpers");

    // then add a handler function
    function click() {
        // using the helper to show a message
        showNotice({
            text: "Two State Button is clicked",
        });
    }
</script>

<div>
    <!-- calling the function on a two state button click -->
    <TwoState {click}>Click Me</TwoState>
</div>

Related sample: Two State Button

You can read detailed information on Messages in the Guides.

Making a button inactive

You can make a button unclickable, if needed. For this, you need to prevent the default click handling via the click handler. Call the preventDefault() method of the Event interface inside the handler function:

<TwoState click={ev => ev.preventDefault()}>
    Click me
</TwoState>

Related sample: Two State Button

Setting the disabled state

Whenever you need to render a disabled Two State button, you can do it with the help of the disabled property. You can either set the property to true or use the property name without a value:

<TwoState disabled={true}>
    Click me 
</TwoState>

It is also possible to specify the disabled property without a value:

<TwoState disabled>Click Me</TwoState>

Related sample: Two State Button

Adding a title

A title is a tooltip text that appears on hovering the mouse cursor over a button and may contain some extra information about the control. Use the title property to add a tooltip for a button:

<TwoState {click} title="Click me and I will change my state">Click Me</TwoState>

Related sample: Two State Button

Styling a button

You can add a custom style to the Two State button control. You need to provide the desired settings in the style section of the application and set the name of the custom class as a value of the css property in the control's tag.

<div class="demo-box">
    <TwoState type={'primary'} css="my" {click}>Click Me</TwoState>
</div>

<style>
    /* styling the button in the default state */
    .demo-box :global(button.my){
        background-color: gold;
        color:white;
    }
</style>

In the above example the style is set as global in order to reach an isolated button control. To make the selector specific for the button, the name of the HTML element ("button") is also set before the class name.

Styling a pressed button

To change the style of a button in the pressed state, add the .pressed selector for the button and provide the desired style attributes for it:

<style>
    /* styling the button in the pressed state */
    .demo-box :global(button.pressed){
        background-color: lightgrey;
        color:white;
    }
</style>

Here's how the stylized Two State button looks like:

Adding icons into buttons

You can add icons into a Two State button to fit your needs. The name of a default icon starts with the wxi- prefix. Here's an example of using icons in different types of Two State buttons, both with and without text:

<!-- an icon button with a text -->
<TwoState icon="wxi-alert">With Icon</TwoState>
<TwoState type={'primary'} icon="wxi-alert" iconActive="wxi-check">With Icon</TwoState>
<TwoState type={'secondary'} icon="wxi-alert">With Icon</TwoState>

<!-- an icon button without a text -->
<TwoState icon="wxi-alert" />
<TwoState type={'primary'} icon="wxi-alert" />
<TwoState type={'secondary'} icon="wxi-alert" />
<TwoState type={'danger'} icon="wxi-alert" />

<!-- a disabled icon button -->
<TwoState disabled icon="wxi-alert" />

Using the default icon pack

The default icons' set is based on the Material Design icons' collection. The list of predefined icons is presented in the snippet. This list is being constantly replenished with new icons.

To use the default icons' pack on a page, you need:

• include the pack on the page as in:

<link rel="stylesheet" href="https://cdn.svar.dev/fonts/wxi/wx-icons.css" />

• use the icon property to specify the name of the desired icon. The name of a default icon is formed as wxi-name. The button in the example below gets an alert icon:

<TwoState icon="wxi-alert">Click Me</TwoState>

Related sample: Two State Button

Setting an icon for the pressed state

Besides the icon for the default state, Two State Button can have a special icon for the pressed state. Use the iconActive property to set an icon for a Two State button in the pressed state. The example below shows how you can add icons for both states of a button:

<TwoState 
    icon="wxi-alert" 
    iconActive="wxi-check">
    With Icon
</TwoState>

Related sample: Two State Button

Customizing the appearance of an icon

If necessary, you can change the appearance of an icon by wrapping it in the <i> tag and using its style attribute. For example:

<TwoState type={'primary'}>
    <i class={"wxi-alert"} style="color:yellow;"/>
    With Icon
</TwoState>