aforemny / material-components-web-elm / Material.Button

Buttons allow users to take actions and make choices with a single tap.

Table of Contents

Resources

Basic Usage

import Material.Button as Button

type Msg
    = Clicked

main =
    Button.text
        (Button.config |> Button.setOnClick Clicked)
        "Text"

Configuration


type alias Config msg =
Internal.Config msg

Configuration of a button

config : Config msg

Default configuration of a button

Configuration Options

setOnClick : msg -> Config msg -> Config msg

Specify a message when the user clicks a button

setIcon : Maybe Icon -> Config msg -> Config msg

Specify whether the button features an icon

setTrailingIcon : Basics.Bool -> Config msg -> Config msg

Specify whether a button's icon is a trailing icon.

Trailing icons are displayed after the button's label rather than before.

setDisabled : Basics.Bool -> Config msg -> Config msg

Specify whether the button is disabled

Disabled buttons cannot be interacted with and do not have no visual interaction effect.

setDense : Basics.Bool -> Config msg -> Config msg

Specify whether a button is dense

Dense buttons feature smaller than normal padding.

setHref : Maybe String -> Config msg -> Config msg

Specify whether a button is a link button.

Link buttons behave like normal HTML5 anchor tags

setTarget : Maybe String -> Config msg -> Config msg

Specify the target for a link button.

Note that this configuration option will be ignored by buttons that do not also set setHref.

setTouch : Basics.Bool -> Config msg -> Config msg

Specify whether touch support is enabled (enabled by default)

Touch support is an accessibility guideline that states that touch targets should be at least 48 x 48 pixels in size. Use this configuration option to disable increased touch target size.

Note: Buttons with touch support will be wrapped in a HTML div element to prevent potentially overlapping touch targets on adjacent elements.

setAttributes : List (Html.Attribute msg) -> Config msg -> Config msg

Specify additional attributes

setMenu : Maybe (Menu msg) -> Config msg -> Config msg

Specify a menu to attach to the button

The button is set as the menu's anchor, however opening the menu still requires the use of Menu.setOpen.

Button Variants

Buttons may appear in different variants. Use text or outlined if you want a button that is flush with the surface, and use raised or unelevated for a button that is contained.

text : Config msg -> String -> Html msg

Text button variant (flush without outline)

outlined : Config msg -> String -> Html msg

Outlined button variant (flush with outline)

raised : Config msg -> String -> Html msg

Raised button variant (contained with elevation)

unelevated : Config msg -> String -> Html msg

Unelevated button variant (contained without elevation)

Button with Icons

To add an icon to a button, use its setIcon configuration option. If you want the icon to be positioned after the button's label, also set the setTrailingIcon configuration option to True.

Button with Leading Icon

Button.text
    (Button.config
        |> Button.setIcon (Just (Button.icon "favorite"))
    )
    "Like"

Button with Trailing Icon

Button.text
    (Button.config
        |> Button.setIcon (Just (Button.icon "favorite"))
        |> Button.setTrailingIcon True
    )
    "Like"

Disabled Button

To disable a button, use its setDisabled configuration option. Disabled buttons cannot be interacted with and have no visual interaction effect.

Button.text
    (Button.config |> Button.setDisabled True)
    "Disabled"

Dense Button

To make a button's text and container margins slightly smaller, use its setDense configuration option.

Button.text
    (Button.config |> Button.setDense True)
    "Dense"

Link Button

To make a button essentially behave like a HTML anchor element, use its setHref configution option. You may use its setTarget configuration option to specify a target.

Button.text
    (Button.config
        |> Button.setHref (Just "https://elm-lang.org")
    )
    "Visit"

Button with Custom Icon

This library natively supports Material Icons. However, you may also include SVG or custom icons such as FontAwesome.


type alias Icon =
Internal.Icon

Icon type

icon : String -> Icon

Material Icon

Button.raised
    (Button.config
        |> Button.setIcon (Just (Button.icon "favorite"))
    )
    "Material Icon"

customIcon : (List (Html.Attribute Basics.Never) -> List (Html Basics.Never) -> Html Basics.Never) -> List (Html.Attribute Basics.Never) -> List (Html Basics.Never) -> Icon

Custom icon

Button.raised
    (Button.config
        |> Button.setIcon
            (Just
                (Button.customIcon Html.i
                    [ class "fab fa-font-awesome" ]
                    []
                )
            )
    )
    "Material Icon"

svgIcon : List (Svg.Attribute Basics.Never) -> List (Svg Basics.Never) -> Icon

SVG icon

Button.raised
    (Button.config
        |> Button.setIcon
            (Just
                (Button.svgIcon
                    [ Svg.Attributes.viewBox "…" ]
                    [-- …
                    ]
                )
            )
    )
    "SVG Icon"

Focus a Button

You may programatically focus a button by assigning an id attribute to it and use Browser.Dom.focus.

Button.text
    (Button.config
        |> Button.setAttributes
            [ Html.Attributes.id "my-button" ]
    )
    "Button"

Button with Menu

Buttons support opening a menu.

Button.text
    (Button.config
        |> Button.setOnClick (OpenChanged True)
        |> Button.setMenu
            (Just <|
                Button.menu
                    (Menu.config
                        |> Menu.setOpen True
                        |> Menu.setOnClose (OpenChanged False)
                    )
                    (ListItem.listItem
                        (ListItem.config
                            |> ListItem.setOnClick (OpenChanged False)
                        )
                        [ text "Orange" ]
                    )
                    [ ListItem.listItem
                        (ListItem.config
                            |> ListItem.setOnClick (OpenChanged False)
                        )
                        [ text "Guava" ]
                    ]
            )
    )
    "Open menu"


type alias Menu msg =
Internal.Menu msg

Menu type

menu : Material.Menu.Config msg -> Material.List.Item.ListItem msg -> List (Material.List.Item.ListItem msg) -> Menu msg

Construct a menu to be used with a button.

Touch Support

Touch support is enabled by default. To disable touch support set a button's setTouch configuration option to False.

Button.text
    (Button.config
        |> Button.setTouch False
    )
    "Click"