thlack.surfs.elements.components — thlack/surfs 2021.01.25

A hiccup-like interface for creating views in Slack applications via blocks. https://api.slack.com/reference/block-kit/blocks

button clj

(button & args)

An interactive component that inserts a button. The button can be a trigger for anything from opening a simple link to starting a complex workflow.

Component usage:

[:button {:action_id "A123" :value "1"} "Click Me!"]

Without props:

[:button "Click Me!"]

Omitting an action id for a button almost never makes sense. The action id may be ignored when using a url button.

channels-select clj

(channels-select props & children)

This select menu will populate its options with a list of public channels visible to the current user in the active workspace.

Component usage:

[:channels-select {:action_id "A123" :initial_channel "C123"}
 [:placeholder "Select channel"]]

checkboxes clj

(checkboxes props & children)

A checkbox group that allows a user to choose multiple items from a list of possible options.

Component usage:

[:checkboxes {:action_id "A123"}
 [:option {:value "1"} "Mushrooms"]
 [:option {:value "2" :selected? true} "Pepperoni"]]

conversations-select clj

(conversations-select props & children)

This select menu will populate its options with a list of public and private channels, DMs, and MPIMs visible to the current user in the active workspace.

Component usage:

[:conversations-select {:action_id "A123"
                        :default_to_current_conversation true
                        :initial_conversation "C123"
                        :filter {:include #{:private}
                                 :exclude_bot_users true
                                 :exclude_external_shared_channels true}}
 [:placeholder "Select conversation"]]

datepicker clj

(datepicker props & children)

An element which lets users easily select a date from a calendar style UI.

Component usage:

[:datepicker {:action_id "A123" :initial_date "2020-11-30"}
 [:placeholder "The date"]]

external-select clj

(external-select props & children)

This select menu will load its options from an external data source, allowing for a dynamic list of options. External selects will treat all options as initial_options, regardless of whether or not the :selected? prop is given.

Component usage:

[:external-select {:action_id "A123" :min_query_length 3}
 [:placeholder "Pizza Toppings"]
 [:option {:value "1"} "Pepperoni"]]

img clj

(img props)

Render function for the image element - not the image layout block. Block kit defines both, and this function is named after the img html element to differentiate between the two.

An element to insert an image as part of a larger block of content.

Component usage:

[:img {:image_url "http://www.fillmurray.com/200/300" :alt_text "It's Bill Murray"}]

multi-channels-select clj

(multi-channels-select props & children)

This multi-select menu will populate its options with a list of public channels visible to the current user in the active workspace.

Component usage:

[:multi-channels-select {:action_id "A123" :max_selected_items 3 :initial_channels ["C123" "C456"]}
 [:placeholder "Select channel"]]

multi-conversations-select clj

(multi-conversations-select props & children)

This multi-select menu will populate its options with a list of public and private channels, DMs, and MPIMs visible to the current user in the active workspace.

Component usage:

[:multi-conversations-select {:action_id "A123"
                              :max_selected_items 3
                              :default_to_current_conversation true
                              :initial_conversations ["C123" "C456"]
                              :filter {:include #{:private}
                                       :exclude_bot_users true
                                       :exclude_external_shared_channels true}}
 [:placeholder "Select conversation"]]

multi-external-select clj

(multi-external-select props & children)

This menu will load its options from an external data source, allowing for a dynamic list of options. External selects will treat all options as initial_options, regardless of whether or not the :selected? prop is given.

Component usage:

[:multi-external-select {:action_id "A123" :max_selected_items 5 :min_query_length 3}
 [:placeholder "Pizza Toppings"]
 [:option {:value "1"} "Pepperoni"]
 [:option {:value "2"} "Mushrooms"]]

multi-static-select clj

(multi-static-select props & children)

A multi-select menu allows a user to select multiple items from a list of options.

Component usage:

[:multi-static-select {:action_id "A123" :max_selected_items 5}
 [:placeholder "Pizza Toppings"]
 [:option {:value "1"} "Mushrooms"]
 [:option {:value "2" :selected? true} "Pepperoni"]
 [:option {:value "3" :selected? true} "Cheese"]]

Supports option groups as well:

[:multi-static-select {:action_id "A123" :max_selected_items 5}
 [:placeholder "Pizza Toppings"]
 [:option-group
  [:label "Veggies"]
  [:option {:value "1"} "Mushrooms"]
  [:option {:value "2" :selected? true} "Peppers"]]
 [:option-group
  [:label "Meats"]
  [:option {:value "3"} "Pepperoni"]
  [:option {:value "4" :selected? true} "Ham"]]]

multi-users-select clj

(multi-users-select props & children)

This multi-select menu will populate its options with a list of Slack users visible to the current user in the active workspace.

Component usage:

[:multi-users-select {:action_id "A123" :max_selected_items 3 :initial_users ["U123" "U456"]}
 [:placeholder "Team captains"]]

overflow clj

(overflow & args)

This is like a cross between a button and a select menu - when a user clicks on this overflow button, they will be presented with a list of options to choose from.

Component usage:

[:overflow {:action_id "A123"}
 [:option {:value "1" :url "https://google.com"} "Google"]
 [:option {:value "2" :url "https://bing.com"} "Bing"]
 [:option {:value "3" :url "https://duckduckgo.com"} "DuckDuckGo"]]

Without props:

[:overflow
 [:option {:value "1" :url "https://google.com"} "Google"]
 [:option {:value "2" :url "https://bing.com"} "Bing"]
 [:option {:value "3" :url "https://duckduckgo.com"} "DuckDuckGo"]]

plain-text-input clj

(plain-text-input props & children)

A plain-text input, similar to the HTML <input> tag, creates a field where a user can enter freeform data. It can appear as a single-line field or a larger textarea using the multiline flag.

Component usage:

[:plain-text-input {:action_id "A123"
                    :initial_value "hello"
                    :multiline true
                    :min_length 1
                    :max_length 100
                    :dispatch_action_config {:trigger_actions_on [:on_enter_pressed]}}
 [:placeholder "Greeting"]]

radio-buttons clj

(radio-buttons props & children)

A radio button group that allows a user to choose one item from a list of possible options.

Component usage:

[:radio-buttons {:action_id "A123"}
 [:option {:value "1"} "Pepperoni"]
 [:option {:value "2" :selected? true} "Pineapple"]
 [:option {:value "3"} "Mushrooms"]]

static-select clj

(static-select props & children)

This is the simplest form of select menu, with a static list of options passed in when defining the element.

Component usage:

[:static-select {:action_id "A123"}
 [:placeholder "Pizza Toppings"]
 [:option {:value "1"} "Mushrooms"]
 [:option {:value "2" :selected? true} "Pepperoni"]
 [:option {:value "3"} "Cheese"]]

Supports option groups as well:

[:static-select {:action_id "A123"}
 [:placeholder "Pizza Toppings"]
 [:option-group
  [:label "Veggies"]
  [:option {:value "1"} "Mushrooms"]
  [:option {:value "2" :selected? true} "Peppers"]]
 [:option-group
  [:label "Meats"]
  [:option {:value "3"} "Pepperoni"]
  [:option {:value "4"} "Ham"]]]

timepicker clj

(timepicker props & children)

An element which allows selection of a time of day.

Component usage:

[:timepicker {:action_id "A123" :initial_time "12:30"}
 [:placeholder "The time"]]

users-select clj

(users-select props & children)

This select menu will populate its options with a list of Slack users visible to the current user in the active workspace.

Component usage:

[:users-select {:action_id "A123" :initial_user "U123"}
 [:placeholder "Team captain"]]