Overview
PopupButton
is simply a convenient subclass of PopupSource that assumes the popup source is a button. PopupButton
takes care of invoking the popup when the user clicks the button.
API
Ancestry: PopupButton → PopupSource → ReactiveElement → HTMLElement
Built with mixins AttributeMarshallingMixin, ComposedFocusMixin, DisabledMixin, FocusVisibleMixin, KeyboardMixin, KeyboardMixin, OpenCloseMixin, ReactiveMixin, RenderUpdatesMixin, and ShadowTemplateMixin.
By default, this uses these elements in the following roles:
- backdrop: Backdrop
- frame: OverlayFrame
- popup: Popup
- source: 'button' element
Extended by classes DropdownList and MenuButton.
$ property
A convenient shortcut for looking up an element by ID in the component's Shadow DOM subtree.
Example: if component's template contains a shadow element
<button id="foo">
, you can use the reference this.$.foo
to obtain
the corresponding button in the component instance's shadow tree.
The $
function is simply a shorthand for getElementById
, so
this.$.foo
is the same as this.shadowRoot.getElementById('foo')
.
Type: object
Defined by ShadowTemplateMixin
backdrop Role property
The class, tag, or template used for the optional backdrop element behind the overlay.
This can help focus the user's attention on the overlay content. Additionally, a backdrop can be used to absorb clicks on background page elements. For example, Dialog uses ModalBackdrop as an overlay backdrop in such a way.
Type: function|string|HTMLTemplateElement
Default: Backdrop
Defined by PopupSource
close(closeResult) method
Close the component (if not already closed).
Some components like AlertDialog want to indicate why or
how they were closed. To support such scenarios, you can supply a value
to the optional closeResult
parameter. This closeResult will be made
available in the whenClosed
promise and the state.closeResult
member.
Parameters:
- closeResult:
object
– an indication of how or why the element closed
Defined by OpenCloseMixin
closed property
True if the element is currently closed.
Type: boolean
Defined by OpenCloseMixin
closed event
Raised when the component closes.
Defined by OpenCloseMixin
close Finished property
True if the element has completely closed.
For components not using asynchronous open/close effects, this property
returns the same value as the closed
property. For elements that have a
true value of state.openCloseEffects
(e.g., elements using
TransitionEffectMixin), this property returns
true only if state.effect
is "close" and state.effectPhase
is
"after".
Type: boolean
Defined by OpenCloseMixin
default State property
The default state for the component. This can be extended by mixins and classes to provide additional default state.
Type: State
Defined by ReactiveMixin
disabled property
True if the component is disabled, false (the default) if not.
The value of this property will be reflected to the disabled
attribute
so that it can be referenced in CSS. Note that this non-native
implementation of the disabled
attribute will not trigger the
:disabled
CSS pseudo-class, so your style rules will have to reference
the presence or absence of the disabled
attribute. That is, instead
of writing
my-component:disabled { ... }
write this instead
my-component[disabled] { ... }
Like the native disabled
attribute, this attribute is boolean. That
means that it's existence in markup sets the attribute, even if set to
an empty string or a string like "false".
Type: boolean
Default: false
Defined by DisabledMixin
frame Role property
The class, tag, or template used to contain the popup content.
The frame element can be used to provide a border around the popup content, and to provide visual effects such as a drop-shadow to help distinguish popup content from background page elements.
Type: function|string|HTMLTemplateElement
Default: OverlayFrame
Defined by PopupSource
horizontal Align property
The alignment of the popup with respect to the source button.
start
: popup and source are aligned on the leading edge according to the text directionend
: popup and source are aligned on the trailing edge according to the text directionleft
: popup and source are left-alignedright
: popup and source are right-aligned- `stretch: both left and right edges are aligned
Type: 'start'|'end'|'left'|'right'|'stretch'
Default: 'start'
Defined by PopupSource
open() method
Open the element (if not already opened).
Defined by OpenCloseMixin
opened property
True if the element is currently opened.
Type: boolean
Defined by OpenCloseMixin
opened event
Raised when the component opens.
Defined by OpenCloseMixin
opened-changed event
Raised when the opened/closed state of the component changes.
Defined by OpenCloseMixin
popup Position property
The preferred direction for the popup.
above
: popup should appear above the sourcebelow
: popup should appear below the source
Type: 'above'|'below'
Default: 'below'
Defined by PopupSource
popup Role property
The class, tag, or template used to define the popup.
The popup element is responsible for handling overlay behavior.
Type: function|string|HTMLTemplateElement
Default: Popup
Defined by PopupSource
render() method
Render the component to the DOM.
This method does nothing if the state has not changed since the last render call.
This method invokes all internal render methods. It then invoked componentDidMount (for first render) or componentDidUpdate (for subsequent renders).
Defined by ReactiveMixin
set State(changes) method
Update the component's state by merging the specified changes on top of the existing state. If the component is connected to the document, and the new state has changed, this returns a promise to asynchronously render the component. Otherwise, this returns a resolved promise.
Parameters:
- changes:
object
– the changes to apply to the element's state
Returns: Promise
- resolves when the new state has been rendered
Defined by ReactiveMixin
should Component Update(nextState) method
Return true if the component should update.
By default, ReactiveMixin
will perform a shallow check of property
values like React's PureComponent. This seems adequate for most web
components. You can override this to always return true (like React's
base Component class), or to perform more specific, deeper checks for
changes in state.
Parameters:
- nextState:
State
– the proposed new state for the element
Returns: boolean
- true if the component should update (rerender)
Defined by ReactiveMixin
source Role property
The class, tag, or template used for the button (or other element) that will invoke the popup.
Type: function|string|HTMLTemplateElement
Default: 'button'
Defined by PopupSource
state property
The component's current state.
The returned state object is immutable. To update it, invoke setState
.
Type: State
Defined by ReactiveMixin
suppress Focus Visibility() method
Temporarily suppress visibility of the keyboard focus until the next keydown event.
This can be useful in components like Menu that actively manage
where the focus is in response to mouse hover activity. If the user uses
the keyboard to invoke a menu, then changes to using the mouse, it can be
distracting to see the focus indicator moving as well. In such
situations, the component can invoke this method (e.g., in response to
mousemove
) to temporarily suppress focus visibility.
Defined by FocusVisibleMixin
symbols.keydown() method
See the symbols documentation for details.
Defined by KeyboardMixin
toggle(opened) method
Toggle the open/close state of the element.
Parameters:
- opened:
boolean
– true if the element should be opened, false if closed.
Defined by OpenCloseMixin
updates property
The attributes and properies that should be applied to the component on render. By default, this is an empty plain object. Your mixin or component can extend this to identify the properties to set on the host element or elements in the shadow subtree.
Type: object
Defined by RenderUpdatesMixin
when Closed() method
This method can be used as an alternative to listening to the "opened-changed" event, particularly in situations where you want to only handle the next time the component is closed.
Returns: Promise
A promise that resolves when the element has
completely closed, including the completion of any asynchronous opening
effect.
Defined by OpenCloseMixin