PaackEng / paack-ui / UI.Button

The UI.Button is a component that can render as a hyperlink, a togglable button, a stylized button, or a clear padded-icon.

Following Elm-UI standards, this component is accessible.

A button can be created and rendered as in the following pipeline:

Element.column []
    [ -- Some UI.TextFields (...)
    , Button.fromLabel "Submit"
        |> Button.cmd FormSend Button.primary
        |> Button.renderElement renderConfig
    ]

Building


type alias Button msg =
UI.Internal.Button.Button msg

The Button msg type is used for describing the component for later rendering.

toggle : String -> (Basics.Bool -> msg) -> Basics.Bool -> Button msg

Toggle is a kind-of button that always contains a toggle-icon and visually looks like an embossed-primary button. The purpose of this button is to toggle between showing/hiding some spammed-content.

Button.toggle "Some Hint for Accessibility" TheTogglingMessage model.isSomethingVisible

disabled : ButtonBody -> Button msg

This Button.disabled builds an embossed-looking, without-message, grayish-colored button. It's another approach for Button.withDisabledIf, helping when you can't compose a message for the desired action at the occasion.

case event of
    Just id ->
        Button.cmd (TriggerEvent id) Button.primary body

    Nothing ->
        Button.disabled body

cmd : msg -> ButtonStyle -> ButtonBody -> Button msg

This is the most common builder. It uses a simple message that is triggered on a click and renders as an embossed and themed button.

Button.fromLabel "Click this Button"
    |> Button.cmd SomeSimpleMessage Button.primary
    |> Button.renderElement renderConfig

redirect : UI.Link.Link -> ButtonStyle -> ButtonBody -> Button msg

Similar to Button.cmd, but instead of a message, it redirects to some path.

Button.fromLabel "Click this Link"
    |> Button.redirect "https://elm-lang.org/" Button.hyperlink
    |> Button.renderElement renderConfig

Content


type alias ButtonBody =
UI.Internal.Button.ButtonBody

The ButtonBody is required when assembling the most-basic Button msg type. It indicates the contents inside of the desired button, like its label or icon.

fromLabel : String -> ButtonBody

Button.fromLabel initiates a button's body with text-content inside it.

Button.fromLabel "Click here"

fromIcon : UI.Icon.Icon -> ButtonBody

Button.fromIcon initiates a button's body with icon-content inside it.

Button.fromIcon (Icon.map "Go to maps")

fromLabeledOnLeftIcon : UI.Icon.Icon -> ButtonBody

Button.fromLabeledOnLeftIcon initiates a button's body with icon-content and it's label on the left.

Button.fromLabeledOnLeftIcon (Icon.map "Go to maps")

fromLabeledOnRightIcon : UI.Icon.Icon -> ButtonBody

Button.fromLabeledOnRightIcon initiates a button's body with icon-content and it's label on the right.

Button.fromLabeledOnRightIcon (Icon.map "Go to maps")

Style


type alias ButtonStyle =
UI.Internal.Button.ButtonStyle

Non-toggle buttons must-be styled. The currently available styles are Hyperlink and Embossed.

A hyperlink-styled: See Button.hyperlink.

An embossed-styled button has paddings and hovering-effects. It's available through its sub-themes: Primary, Danger, Light, and Clear. These only change background and text color.

hyperlink : ButtonStyle

A hyperlink-styled button looks like classical web links: Blue with an underline.

primary : ButtonStyle

The primary action's theme. This button usually commits the main task.

danger : ButtonStyle

This is the danger-theme, and it's reddish for enforcing the user's attention.

light : ButtonStyle

This is the light-theme, mostly used for less-important actions.

clear : ButtonStyle

This is the clear-theme, mostly used on icons where the background color isn't needed.

switchedOn : ButtonStyle

The switched on state for a button. Any active button can be in a a possible "On" state.

Width


type alias ButtonWidth =
UI.Internal.Button.ButtonWidth

Describes a compatible width.

withWidth : ButtonWidth -> Button msg -> Button msg

Button.withWidth changes the width of the button.

Button.withWidth Button.widthFull someButton

widthFull : ButtonWidth

The button's width will fill its container.

widthRelative : ButtonWidth

The button will have the exact width to fit its contents.

NOTE: Default behaviour.

Size

withSize : UI.Internal.Size.Size -> Button msg -> Button msg

With Button.withSize, you'll be able to scale the button between the standard sizes.

The sizes (in height) are: Large - 60px; Medium - 48px; Small - 36px; Extra Small - 24px.

Button.withSize Size.large someButton

NOTE: Button's default size is Size.medium

Conditional states

withDisabledIf : Basics.Bool -> Button msg -> Button msg

After asserting some condition, Button.withDisabledIf will attempt to set the button to a visually-noticeable disabled state (a grayish button where the action can no longer be triggered).

Button.fromLabel "Send Someting"
    |> Button.cmd (QuerySend "Something") Button.primary
    |> Button.withDisabledIf (model.queryResult != QueryNotAsked)
    |> Button.renderElement renderConfig

NOTE: In case the button is a toggle or the condition resolves as False, nothing will happen.

Identification

withId : Maybe String -> Button msg -> Button msg

With Button.withId, you can add an HTML ID attribute to the button element.

Button.withId (Just "id") someButton

Rendering

renderElement : UI.RenderConfig.RenderConfig -> Button msg -> Element msg

End of the builder's life. The result of this function is a ready-to-insert Elm UI's Element.

Component handling

map : (a -> b) -> Button a -> Button b

Transform the messages produced by the component.