Skip to main content

Button

Shadow dwc-button
Java API

A Button component is a fundamental user interface element used in application development to create interactive elements that trigger actions or events when clicked or activated. It serves as a clickable element that users can interact with to perform various actions within an application or website.

The primary purpose of the Button component is to provide a clear and intuitive call-to-action for users, guiding them to perform specific tasks such as submitting a form, navigating to another page, triggering a function, or initiating a process. Buttons are essential for enhancing user interactions, improving accessibility, and creating a more engaging user experience.

Show Code

Usages​

The Button class is a versatile component that is commonly used in various situations where user interactions and actions need to be triggered. Here are some typical scenarios where you might need a button in your application:

  1. Form Submission: Buttons are often used to submit form data. For example, in an application, you can use:
  • A "Submit" button to send data to the server
  • A "Clear" button to remove any information already present in the form
  1. User Actions: Buttons are used to allow users to perform specific actions within the application. For instance, you can have a button labeled:
  • "Delete" to initiate the deletion of a selected item
  • "Save" to save changes made to a document or page.

  1. Confirmation Dialogs: Buttons are often included in Dialog components built for various purposes to provide options for users to confirm or cancel an action, or any other functionality that is built into the Dialog you're using.

  2. Interaction Triggers: Buttons can serve as triggers for interactions or events within the application. By clicking a button, users can initiate complex actions or trigger animations, refreshing content, or updating the display.

  3. Navigation: Buttons can be used for navigation purposes, such as moving between different sections or pages within an application. Buttons for navigation could include:

  • "Next" - Takes the user to the next page or section of the current application or page.
  • "Previous" - Returns the user to the previous page of the application or section they're in.
  • "Back" Returns the user to the first part of the application or page they're in.

Constructors​

The Button class has three constructors:

  1. Button()
    : Creates an empty Button without any text inside the component.
  2. Button(String text)
    : Creates a Button with text inside the component.
  3. Button(String text, EventListener<ButtonClickEvent> onClickListener)
    : Creates a Button with text inside the component, and an
    EventListener
    for a
    ButtonClickEvent
    which fires when a user clicks on the Button.

Here is an example of how to create a Button object:

Button submit = new Button("Submit");

Adding Icons to Buttons​

In addition to, or instead of having text on a Button, it is possible to add an icon to a button as well. To add these icons, set the button's text to have an <html> tag, with a <dwc-icon> tag inside with the name attribute set accordingly. In addition to an icon, include text to the left or right of the <dwc-icon> tag to include a label as well. Icons added to the left and/or right of the button should be done using the prefix and suffix slots.

To read more about customizing, configuring and styling icons, read this page.

tip

Icons added in this way will automatically be configured to match the theme of the Button, but need to be manually configured if a different sized icon is desired when changing Button expanse.

Below are examples of buttons with text to the left and right, as well as a button with only an icon:

Show Code

Names​

The Button component utilizes naming, which is used for accessibility. When a name is not explicitly set, the label of the Button will be used instead. However, some icons do not have labels, and only display non-text elements, such as icons. In this case, it is expedient to use the setName() method to ensure that the Button component created complies with accessibility standards.

Disabling a Button​

Button components, like many others, can be disabled to convey to a user that a certain action is not yet or is no longer available. A disabled button will decrease the opacity of the button, and is available for all button themes and expanses.

Show Code


Disabling a button can be done at any time in the code by using the

setEnabled(boolean enabled)
function. For added convenience, a button can also be disabled when clicked using the built-in
setDisabledOnClick(boolean enabled)
function.

In some applications, clicking a button triggers a long-running action. In most cases, the application might want to ensure that only a single click is processed. This can be an issue in high-latency environments when the user clicks the button multiple times before the application has had a chance to start processing the resulting action.

tip

Disabling on click not only helps optimize the processing of actions, but also prevents the developer from needing to implement this behavior on their own, as this method has been optimized to reduce round trip communications.

Styling​

Themes​

Button components come with

14 discrete themes
built in for quick styling without the use of CSS. These themes are pre-defined styles that can be applied to buttons to change their appearance and visual presentation. They offer a quick and consistent way to customize the look of buttons throughout an application.

While there are many use cases for each of the various themes, some examples uses are:

  • Danger: Actions with severe consequences, such as clearing filled-out information, or permanently deleting an account/data is represents a good use case for buttons with the Danger theme.
  • Default: The default theme is appropriate for actions throughout an application that do not require special attention and that are generic, such as toggling a setting.
  • Primary: This theme is appropriate as a main "call-to-action" on a page, such as signing up, saving changes, or continuing to another page.
  • Success: Success themed buttons are excellent for visualizing successful completion of an element in an application, such as the submission of a form or completion of a sign-up process. The success theme can by programmatically applied once a successful action has been completed.
  • Warning: Warning buttons are useful to indicate users they are about to perform a potentially risky action, such as when navigating away from a page with unsaved changes. These actions are often less impactful than those that would use the Danger theme.
  • Gray: Good for subtle actions, such as minor settings or actions that are more supplementary to a page, and not part of the main functionality.
  • Info: The Info theme is a good choice to provide clarifying, additional information to a user when pushed.

Shown below are example buttons with each of the supported Themes applied:

Show Code

Expanses​

The following

Expanses values
allow for quick styling without using CSS. This allows for manipulation of the Button's dimensions without having to explicitly set it using any styling. In addition to simplifying styling, it also helps create and maintain a uniformity in your application. The default Button expanse is Expanse.MEDIUM.

Different sizes are often appropriate for different uses:

  • Larger expanse values are suited to buttons which should grab attention, emphasize functionality or are integral to the core functionality of an application or page.
  • Medium expanse buttons, the default size, should be utilized as a "standard size", when a button's behavior is no more or less important than other similar components.
  • Smaller expanse values should be used for buttons that do not have integral behaviors in the application, and serve a more supplementary or utilitarian role, rather than play an important part in user interaction. This includes Button components being used only with icons for utilitarian purposes.

Below are the various expanses supported for the Button component:

Show Code

Shadow Parts​

These are the various parts of the shadow DOM for the component, which will be required when styling via CSS is desired.

Loading...

Slots​

Listed below are the slots available for utilization within the Button component. These slots act as placeholders within the component that control where the children of a customized element should be inserted within the shadow tree.

Loading...

CSS Properties​

These are the various CSS properties that are used in the component, with a short description of their use.

Loading...

Reflected Attributes​

The reflected attributes of a component will be shown as attributes in the rendered HTML element for the component in the DOM. This means that styling can be applied using these attributes.

Loading...

Dependencies​

This component relies on the following components - see the related article for more detailed styling information:

Loading...

Best Practices​

To ensure an optimal user experience when using the Button component, consider the following best practices:

  1. Proper Text: Use clear and concise text for text within your Button component to provide a clear indication of its purpose.

  2. Appropriate Visual Styling: Consider the visual styling and theme of the Button to ensure consistency with your application's design. For example:

  • A "Cancel" Button component should be styled with the appropriate theme or CSS styling to ensure users are sure they want to cancel an action
  • A "Confirm" Button would have a different styling from a "Cancel" button, but would similarly stand out to ensure that users know this is a special action.

  1. Efficient Event Handling: Handle Button events efficiently and provide appropriate feedback to users. Refer to this section to review efficient event adding behaviors.

  2. Testing and Accessibility: Test the Button's behavior in different scenarios, such as when it is disabled or receives focus, to ensure a smooth user experience. Follow accessibility guidelines to make the Button usable for all users, including those who rely on assistive technologies.