Popup Button

Components > User Interaction > Popup Button

Use this component to...

Display secondary activity in a small popup window that displays when the button is pressed

See this component in action...

Test out this component in a hosted version of the sample app

Overview

The popup button looks like a dropdown button at rest but can be used to display a small amount of content in a popup window when pressed. This gives you the freedom to create a small custom interaction in a popup without needing a dedicated enterprise component for the interaction.

To close the popup window, the user can click anywhere outside of the popup button or its popup window, press the popup button a second time, or press the Escape key.

The popup button is for small interactions only and is not intended for the more complex interactions that we typically see in a stacked view or dialog box. It’s easy for the user to accidentally close a popup button by clicking outside of it, where in a stacked view or dialog box the user has to explicitly press a specific button to close the secondary activity.

Because of this, you should use a stacked view instead of a popup button:

If the user would be inconvenienced if the popup accidentally closes
If the interaction content is large enough to require responsiveness or any degree of scrolling
If the interaction requires the use of the Escape key, since this key closes the popup

Popup button displaying its menu after the button is pressed

Text and icons

Popup buttons can display a text label, an icon, or both.

Styling

Popup buttons support the following styling:

Use secondary styling for most popup buttons. The styling for secondary buttons is visually lighter to prevent the button from distracting the user’s eye from the data.
Use primary styling for a popup button that performs the primary action in the view. The styling for primary buttons is visually heavy in order to draw attention to the button’s importance. There should be no more than one primary button in each view (or at most in each display block).

Usage

Popup buttons can be used anywhere in a function view.

Development

Web component development

Component reference

rui-popup-button

Module: rui-buttons - Package: @jkhy/responsive-ui-wc

Displays a small popup window when pressed

Name	Type	Default	Description
text	string	''	Text displayed in the button.
buttonStyle	string	'secondary'	Specifies the styling displayed for the button: One of “primary”, “secondary”, or “destructive” Use a value of “secondary” for most buttons. Use a value of “primary” for a button that performs the primary action in the view. There should be no more than one primary button in each view (or at most in each display block). Use a value of “destructive” if pressing the button triggers a significant, destructive action like deletion. This button style should be used sparingly.
buttonSize	string	'medium'	Specifies the relative size of the button: One of “medium” or “small” Use the default value of “medium” for most buttons. You can optionally use the “small” size for buttons in a toolbar if you’re looking for more compactness.
iconType	string	''	The name of the icon to display in an icon button. You can find a list of all enterprise icons here. The use of custom icons is also supported.
alignment	string	'left'	One of “left” or “right”. Describes which button edge the menu aligns to. Use a value of “right” if the button is towards the far right edge of the app and the dropdown menu is getting clipped on the right.
isDisabled	boolean	false	Specifies whether the button is disabled.
dropdownWidth	string	'auto'	Specifies the width of the dropdown panel. Leave at the default value of ‘auto’ unless you need to specify a specific pixel or percentage width. Use CSS notation appropriate for the CSS “width” attribute.
isMenuDisplayed	boolean	false	The popup menu is typically opened and closed by clicking on and off the button. You can control the menu display by binding this boolean trigger property. Bind this property to a backing boolean value in your controller, then set the backing value to true whenever you want to programmatically show the menu, and false to hide the menu.
rui-popup-button-is-menu-displayed-change	event		Event fired when the isMenuDisplayed property value changes. You must reset the backing boolean value in your controller to which the isMenuDisplayed property is bound when this event fires.

Implementation

Begin by importing the rui-buttons module into your application.

Import the module

// import into app.module
import '@jkhy/responsive-ui-wc/components/rui-buttons/rui-buttons-imports';

Use the rui-popup-button component to implement a popup button. Specify the button’s text with the text property.

Popup button example

<rui-popup-button text="Settings"></rui-popup-button>

Within the rui-popup-button element, build out the markup needed for your popup menu. If the dropdown needs to be wider than the button to accommodate the content, set the dropdownWidth property.

Popup button content

<rui-popup-button text="Popup Button" dropdownWidth="500px">

    <!-- popup content goes here -->

</rui-popup-button>

Sometimes there may be a need to programmatically open or close the popup menu. If the popup contains a small form with submit and/or cancel buttons, you’ll need to use the isMenuDisplayed property to close the popup menu. Bind isMenuDisplayed to a backing boolean property, and set that property to true when you want to open the menu and false when you want to close the menu. Listen for the rui-popup-button-is-menu-displayed-change event and set your backing property to the event detail to reset the value.

Programmatically show/hide popup button

<rui-popup-button text="Popup Button" dropdownWidth="500px" [isMenuDisplayed]="isMenuDisplayed" (rui-popup-button-is-menu-displayed-change)="isMenuDisplayed = $event.detail">

    <!-- popup content goes here -->

</rui-popup-button>

Use buttonStyle to specify the styling to use:

Leave this property at its default of “secondary” for most buttons.
Use a value of “primary” for a button that performs the primary action in the view. There should be no more than one primary button in each view (or at most in each display block).

Bind isDisabled to a value of true to disable the button.

Buttons in Responsive UI almost always display text as their content, but you can also display icon buttons in limited cases. To display an icon as the button content, set the iconType property to one of the enterprise icon names. Use icon buttons sparingly, and only with standard icons that are very well understood by the user, such as print, edit, add-new, etc. You can find a list of all enterprise icons here.

Custom icons are also possible using the custom-icon slot. You can find more information on implementing custom icons on the icon component doc.

Icon-only popup button

<rui-popup-button iconType="settings" buttonStyle="primary">
    ...
</rui-popup-button>

If you’re looking for more compactness for buttons in a toolbar, you can set the buttonSize property to a value of “small”. This button size must only be used for buttons in a toolbar.

Small popup button

<rui-popup-button text="Settings" buttonSize="small">
    ...
</rui-popup-button>

Angular wrapper development

Wrapper reference

jha-popup-button

Module: JhaLayoutModule - Package: @jkhy/responsive-ui-angular

Displays a small popup window when pressed

Name	Type	Default	Description
jhaText	string	''	Text displayed in the button.
jhaButtonStyle	string	'Secondary'	Specifies the styling displayed for the button: One of “Primary”, “Secondary”, or “Destructive” Use a value of “Secondary” for most buttons. Use a value of “Primary” for a button that performs the primary action in the view. There should be no more than one primary button in each view (or at most in each display block). Use a value of “Destructive” if pressing the button triggers a significant, destructive action like deletion. This button style should be used sparingly.
jhaButtonSize	string	'medium'	Specifies the relative size of the button: One of “medium” or “small” Use the default value of “medium” for most buttons. You can optionally use the “small” size for buttons in a toolbar if you’re looking for more compactness.
jhaIconType	string	''	The name of the icon to display in an icon button. You can find a list of all enterprise icons here. The use of custom icons is also supported.
jhaTooltip	string	''	Tooltip displayed when the mouse hovers over the button
jhaAlignment	string	'Left'	One of “Left” or “Right”. Describes which button edge the menu aligns to. Use a value of “Right” if the button is towards the far right edge of the app and the dropdown menu is getting clipped on the right.
jhaIsDisabled	boolean	false	Specifies whether the button is disabled.
dropdownWidth	string	'auto'	Specifies the width of the dropdown panel. Leave at the default value of ‘auto’ unless you need to specify a specific pixel or percentage width. Use CSS notation appropriate for the CSS “width” attribute.
jhaIsMenuDisplayed	boolean	false	The popup menu is typically opened and closed by clicking on and off the button. You can control the menu display by binding this boolean trigger property. Bind this property to a backing boolean value in your controller, then set the backing value to true whenever you want to programmatically show the menu, and false to hide the menu.
jhaIsMenuDisplayedChange	event		Event fired when the jhaIsMenuDisplayed property value changes. You must reset the backing boolean value in your controller to which the jhaIsMenuDisplayed property is bound when this event fires.

Implementation

Begin by importing the JhaButtonsModule module into your application.

Import the module

// import into app.module
import { JhaButtonsModule } from '@jkhy/responsive-ui-angular/jha-buttons';

@NgModule({
    imports: [
        ...
        JhaButtonsModule,
        ...
    ]
})

export class AppModule(){}

Use the rui-popup-button component to implement a popup button. Specify the button’s text with the jhaText property.

Popup button example

<jha-popup-button jhaText="Settings"></jha-popup-button>

Within the jha-popup-button element, build out the markup needed for your popup menu. If the dropdown needs to be wider than the button to accommodate the content, set the jhaDropdownWidth property.

Popup button content

<jha-popup-button text="Popup Button" jhaDropdownWidth="500px">

    <!-- popup content goes here -->

</jha-popup-button>

Sometimes there may be a need to programmatically open or close the popup menu. If the popup contains a small form with submit and/or cancel buttons, you’ll need to use the jhaIsMenuDisplayed property to close the popup menu. Bind jhaIsMenuDisplayed to a backing boolean property, and set that property to true when you want to open the menu and false when you want to close the menu.

Programmatically show/hide popup button

<jha-popup-button jhaText="Settings" jhaDropdownWidth="300px" [(jhaIsMenuDisplayed)]="isMenuDisplayed">

    <!-- popup content goes here -->

</jha-popup-button>

Use jhaButtonStyle to specify the styling to use:

Leave this property at its default of “Secondary” for most buttons.
Use a value of “Primary” for a button that performs the primary action in the view. There should be no more than one primary button in each view (or at most in each display block).

Bind jhaIsDisabled to a value of true to disable the button.

Custom icons are also possible using the custom-icon slot. You can find more information on implementing custom icons on the icon component doc.

Icon-only popup button

<jha-popup-button jhaIconType="Settings" jhaButtonStyle="Primary">
    ...
</jha-popup-button>

Buttons typically auto-size to fit their content, but in certain cases you may want to define a specific width for the button. You can use the jhaWidth property to specify a specific pixel or percentage width. If you do this, use CSS notation appropriate for the CSS “width” attribute.

Popup button with custom width

<jha-popup-button jhaText="Settings" jhaWidth="250px">
    ...
</jha-popup-button>

If you’re looking for more compactness for buttons in a toolbar, you can set the jhaButtonSize property to a value of “small”. This button size must only be used for buttons in a toolbar.

Small popup button

<jha-popup-button jhaText="Settings" jhaButtonSize="Small">
    ...
</jha-popup-button>

Component playground

Design

Figma design

Figma design info

You can find this component in the Components - Buttons page in the Figma UI Kit.

Dev Component	Design Component Name
Popup button	RUI / Buttons / Button Available values for the Style property: Primary Secondary Disabled Switch on the IconOnly property if the button only displays an icon.

Dev Component

Design Component Name

Popup button

RUI / Buttons / Button

Available values for the Style property:

Primary
Secondary
Disabled

Switch on the IconOnly property if the button only displays an icon.

Adobe XD design

Adobe XD design info

You can find this component in these artboards in the Adobe XD design samples:

Sample App - Buttons

Dev Component	Design Component Name
Popup button - primary	JHA / Buttons / Button / Primary
Popup button - secondary	JHA / Buttons / Button / Secondary
Popup button - disabled	JHA / Buttons / Button / Disabled

Support options

Have questions on this topic?

Join the Responsive UI team in Microsoft Teams to connect with the community.

See something in this page that needs to change?

Send us feedback on this page.

Last updated Wed Sep 25 2024