Buttons

Design

Resting Disabled Comment
The simple button can be used in different contexts: in the tool bar to access primary actions (Ask question), in the footer of a form or dialog to confirm and submit the inputs (OK), and within forms to access additional functionality (Browse).
The caution button is used to confirm actions that are high risk.
The subtle button is used where an action that is often not the focus of the page - it has a subtle design that provides a lower weight in the resting state's visual hierarchy.

Button groups

There are two types of button group, combined and separate. Combined groups are for buttons which directly relate to each other, to the extent that they are part of one overall choice or action. Separate groups keep the individual buttons separate, as their actions are not directly related.

The default type is the Combined button group, which creates a set of related buttons in a combined style:

Separate button groups are a simple wrapper for buttons, keeping the buttons themselves separate:

Separate button groups often aren't necessary if the buttons are already contained in another element, for example within a Header actions item.

Pressed buttons

Pressed buttons can be used in combined groups to indicate interactions such as choosing filters. In most cases, only one button in the group will be pressed at a time:

Note this is not the same as the Toggle control which toggles between two named states.

Dimensions

In the majority of cases, the default button size is the right thing to use. In some cases it is necessary to override this by manually setting dimensions.

Buttons can be set to four sizes, with a minimum width for each that will scale horizontally to allow for internationalisation. While there are larger button sizes all care must be taken to craft a concise button label.

Example Width (pixels) Comment
31 Used for displaying a familiar action that can be represented by a single icon.
80 The most commonly used button size.
140 Useful when more information is needed to convey the action.
200 Useful when more information is needed to convey the action.

Code

API: stable
Example Element Code
Default button. 

                                                                              <button class="ace-button" type="button"><span>Default</span></button>

                                                                          <% ace.Button(Array("text", "Default")) %>
Caution button. 

                                                                              <button class="ace-button ace-button-caution" type="button"><span>Caution</span></button>

                                                                          <% ace.Button(Array(_
                                                                              "text", "Caution",_
                                                                              "type", "caution"_
                                                                          )) %>
Subtle button. 

                                                                              <button class="ace-button ace-button-subtle" type="button"><span>Subtle</span></button>

                                                                          <% ace.Button(Array(_
                                                                              "text", "Subtle",_
                                                                              "type", "subtle"_
                                                                          )) %>
'Link buttons' are used when the design requires a link set next to a button; or for cases where the code requires a BUTTON element, but the design requires a link style.
Icons for link buttons are placed before the text rather than afterwards.
Buttons can include an icon. Note the icon can have additional alternate text if required; but don't set the same string for both. 

                                                                              <button class="ace-button ace-button-icon ace-button-icon" type="button"><span><span class="ace-text">Close</span><span class="ace-icon ace-icon-icon-close"></span></span></button>

                                                                          <% ace.Button(Array(_
                                                                            "icon", "control-close",_
                                                                            "text", "Close",_
                                                                            "type", "icon"_
                                                                          )) %>
Icon-only buttons have a modifier class and wrap an instance of ace-icon. Note there must always be descriptive text available within the button, so it is included within the icon. 

                                                                              <button class="ace-button ace-button-icon ace-button-icon" type="button"><span><span class="ace-icon ace-icon-control-close">Close</span></span></button>

                                                                          <% ace.Button(Array(_
                                                                            "icon", "control-close",_
                                                                            "iconText", "Close",_
                                                                            "type", "icon"_
                                                                          )) %>
Icon-only subtle button. 

                                                                              <button class="ace-button ace-button-subtle ace-button-icon" type="button"><span><span class="ace-icon ace-icon-control-close">Close</span></span></button>

                                                                          <% ace.Button(Array(_
                                                                            "icon", "control-close",_
                                                                            "iconText", "Close",_
                                                                            "type", "subtle"_
                                                                          )) %>
Setting button to collapsible makes the text hidden on small screens. 

                                                                              <button class="ace-button ace-button-subtle ace-button-icon ace-button-collapsible" type="button"><span><span class="ace-text">Close</span><span class="ace-icon ace-icon-control-close">Close</span></span></button>

                                                                          <% ace.Button(Array(_
                                                                            "text", "Close",_
                                                                            "type", "default",_
                                                                            "icon", "control-close",_
                                                                            "iconText", "Close",_
                                                                            "collapsible", "true"_
                                                                          )) %>
To set a button to disabled style use the native disabled attribute in fully quoted form. 

                                                                              <button class="ace-button" disabled="disabled" type="button"><span>Disabled</span></button>

                                                                          <% ace.Button(Array(_
                                                                            "text", "Disabled",_
                                                                            "disabled", "disabled"_
                                                                          )) %>
                                                                          

                                                                              <button class="ace-button ace-button-caution" disabled="disabled" type="button"><span>Caution disabled</span></button>

                                                                          <% ace.Button(Array(_
                                                                            "text", "Caution disabled",_
                                                                            "type", "caution",_
                                                                            "disabled", "disabled"_
                                                                          )) %>
Sizes are set with modifier classes. 

                                                                              <button class="ace-button ace-button-small" type="button"><span>?</span></button>

                                                                          <% ace.Button(Array(_
                                                                            "text", "?",_
                                                                            "size", "small"_
                                                                          )) %>
                                                                          

                                                                              <button class="ace-button ace-button-medium" type="button"><span>Medium</span></button>

                                                                          <% ace.Button(Array(_
                                                                            "text", "Medium",_
                                                                            "size", "medium"_
                                                                          )) %>
                                                                          

                                                                              <button class="ace-button ace-button-large" type="button"><span>Large</span></button>

                                                                          <% ace.Button(Array(_
                                                                            "text", "Large",_
                                                                            "size", "large"_
                                                                          )) %>
                                                                          

                                                                              <button class="ace-button ace-button-xlarge" type="button"><span>Extra large</span></button>

                                                                          <% ace.Button(Array(_
                                                                            "text", "Extra large",_
                                                                            "size", "xlarge"_
                                                                          )) %>
Buttons can be grouped by adding the ace-button-group wrapper element. 

                                                                              <div class="ace-button-group">
                                                                                    <button class="ace-button" type="button"><span>Three</span></button>
                                                                                    <button class="ace-button" type="button"><span>Related</span></button>
                                                                                    <button class="ace-button" type="button"><span>Actions</span></button>
                                                                              </div>

                                                                          <% ace.ButtonGroup(Array())
                                                                            ace.Button(Array("text", "Three"))
                                                                            ace.Button(Array("text", "Related"))
                                                                            ace.Button(Array("text", "Actions"))
                                                                          ace.ButtonGroupEnd %>
Buttons can be grouped but kept separate by adding the ace-button-group wrapper element with the additional class ace-button-group-separate. 

                                                                              <div class="ace-button-group ace-button-group-separate">
                                                                                    <button class="ace-button" type="button"><span>Bulk upload</span></button>
                                                                                    <button class="ace-button" type="button"><span>Export to excel</span></button>
                                                                                    <button class="ace-button" type="button"><span>Print</span></button>
                                                                              </div>

                                                                          <% ace.ButtonGroup(Array("type", "separate"))
                                                                            ace.Button(Array("text", "Bulk upload"))
                                                                            ace.Button(Array("text", "Export to excel"))
                                                                            ace.Button(Array("text", "Print"))
                                                                          ace.ButtonGroupEnd %>
Pressed button groups can only have one button pressed at a time. Follow the general behaviour of radio buttons. To set a button to pressed, use the aria-pressed attribute set to true or false. 

                                                                              <div class="ace-button-group">
                                                                                    <button class="ace-button ace-button-pressed" aria-pressed="true" type="button"><span>Apples</span></button>
                                                                                    <button class="ace-button ace-button-pressed" aria-pressed="false" type="button"><span>Oranges</span></button>
                                                                                    <button class="ace-button ace-button-pressed" aria-pressed="false" type="button"><span>Bananas</span></button>
                                                                              </div>

                                                                          <% ace.ButtonGroup(Array("type", "separate"))
                                                                            ace.Button(Array(_
                                                                              "text", "Apples",_
                                                                              "type", "pressed",_
                                                                              "aria-pressed", "true"_
                                                                            ))
                                                                            ace.Button(Array(_
                                                                              "text", "Oranges",_
                                                                              "type", "pressed",_
                                                                              "aria-pressed", "false"_
                                                                            ))
                                                                            ace.Button(Array(_
                                                                              "text", "Bananas",_
                                                                              "type", "pressed",_
                                                                              "aria-pressed", "false"_
                                                                            ))
                                                                          ace.ButtonGroupEnd %>