14.0.0 • Published 4 months ago

@material/menu-surface v14.0.0

Weekly downloads
50,061
License
MIT
Repository
github
Last release
4 months ago

Menu Surface

The MDC Menu Surface component is a reusable surface that appears above the content of the page and can be positioned adjacent to an element. Menu Surfaces require JavaScript to properly position themselves when opening.

Design & API Documentation

Installation

npm install @material/menu-surface

Usage

HTML Structure

<div class="mdc-menu-surface">
...
</div>

Styles

@import "@material/menu-surface/mdc-menu-surface";

JavaScript Instantiation

import {MDCMenuSurface} from '@material/menu-surface';

const menuSurface = new MDCMenuSurface(document.querySelector('.mdc-menu-surface'));

See Importing the JS component for more information on how to import JavaScript.

Variants

Anchors and Positioning

Anchored To Parent

The menu surface can be positioned to automatically anchor to a parent element when opened.

<div id="toolbar" class="toolbar mdc-menu-surface--anchor">
  <div class="mdc-menu-surface">
  ...
  </div>
</div>

Anchor To Element Within Wrapper

The menu surface can be positioned to automatically anchor to another element, by wrapping the other element with the anchor class.

<div class="mdc-menu-surface--anchor">
  <button id="menu-surface-button">Open Menu Surface</button>
  <div class="mdc-menu-surface">
  ...
  </div>
</div>

Fixed Position

The menu surface can use fixed positioning when being displayed.

<div class="mdc-menu-surface mdc-menu-surface--fixed">
...
</div>

Or in JS:

// ...
menuSurface.setFixedPosition(true);

Absolute Position

The menu surface can use absolute positioning when being displayed. This requires that the element containing the menu (body if using hoistMenuToBody()) has the position: relative style.

<div class="mdc-menu-surface">
...
</div>
// ...
menuSurface.hoistMenuToBody(); // Not required if the menu-surface is already positioned on the body.
menuSurface.setAbsolutePosition(100, 100);

Style Customization

CSS Classes

CSS ClassDescription
mdc-menu-surfaceMandatory.
mdc-menu-surface--animating-openIndicates the menu surface is currently animating open. This class is removed once the animation completes.
mdc-menu-surface--openIndicates the menu surface is currently open, or is currently animating open.
mdc-menu-surface--animating-closedIndicates the menu surface is currently animating closed. This class is removed once the animation completes.
mdc-menu-surface--anchorUsed to indicate which element the menu should be anchored to.
mdc-menu-surface--fixedUsed to indicate that the menu is using fixed positioning.

Sass Mixins

MixinDescription
mdc-menu-surface-ink-color($color)Sets the color property of the mdc-menu-surface.
mdc-menu-surface-fill-color($color)Sets the background-color property of the mdc-menu-surface.
mdc-menu-surface-shape-radius($radius, $rtl-reflexive)Sets the rounded shape to menu surface with given radius size. Set $rtl-reflexive to true to flip radius values in RTL context, defaults to false.

Constants & Types

Constant NameDescription
CornerEnum for representing an element corner for positioning the menu-surface. See constants.ts.
Type NameDescription
MDCMenuDimensionsWidth/height of an element. See types.ts.
MDCMenuDistanceMargin values representing the distance from anchor point that the menu surface should be shown. See types.ts.
MDCMenuPointX/Y coordinates. See types.ts.

MDCMenuSurface Properties and Methods

PropertyValue TypeDescription
openBooleanProxies to the foundation's isOpen/(open, close) methods.
quickOpenBooleanProxies to the foundation's setQuickOpen() method.
Method SignatureDescription
setAnchorCorner(Corner) => voidProxies to the foundation's setAnchorCorner(Corner) method.
setAnchorMargin(Partial<MDCMenuDistance>) => voidProxies to the foundation's setAnchorMargin(Partial<MDCMenuDistance>) method.
setFixedPosition(isFixed: boolean) => voidAdds the mdc-menu-surface--fixed class to the mdc-menu-surface element. Proxies to the foundation's setIsHoisted() and setFixedPosition() methods.
setAbsolutePosition(x: number, y: number) => voidProxies to the foundation's setAbsolutePosition(x, y) method. Used to set the absolute x/y position of the menu on the page. Should only be used when the menu is hoisted to the body.
setMenuSurfaceAnchorElement(element: Element) => voidChanges the element used as an anchor for menu-surface positioning logic. Should be used with conjunction with hoistMenuToBody().
hoistMenuToBody() => voidRemoves the menu-surface element from the DOM and appends it to the body element. Should be used to overcome overflow: hidden issues.
setIsHoisted() => voidProxies to the foundation's setIsHoisted method.
getDefaultFoundation() => MDCMenuSurfaceFoundationReturns the foundation.

Events

Event NameDataDescription
MDCMenuSurface:closednoneEvent emitted after the menu surface is closed.
MDCMenuSurface:openednoneEvent emitted after the menu surface is opened.

Usage Within Frameworks

If you are using a JavaScript framework, such as React or Angular, you can create a Menu Surface for your framework. Depending on your needs, you can use the Simple Approach: Wrapping MDC Web Vanilla Components, or the Advanced Approach: Using Foundations and Adapters. Please follow the instructions here.

MDCMenuSurfaceAdapter

Method SignatureDescription
addClass(className: string) => voidAdds a class to the root element.
removeClass(className: string) => voidRemoves a class from the root element.
hasClass(className: string) => booleanReturns a boolean indicating whether the root element has a given class.
hasAnchor: () => booleanReturns whether the menu surface has an anchor for positioning.
notifyClose() => voidDispatches an event notifying listeners that the menu surface has been closed.
notifyOpen() => voidDispatches an event notifying listeners that the menu surface has been opened.
isElementInContainer(el: Element) => booleanReturns true if the el Element is inside the mdc-menu-surface container.
isRtl() => booleanReturns boolean indicating whether the current environment is RTL.
setTransformOrigin(value: string) => voidSets the transform origin for the menu surface element.
isFocused() => booleanReturns a boolean value indicating whether the root element of the menu surface is focused.
saveFocus() => voidStores the currently focused element on the document, for restoring with restoreFocus.
restoreFocus() => voidRestores the previously saved focus state, by making the previously focused element the active focus again.
isFirstElementFocused() => booleanReturns a boolean value indicating if the first focusable element of the menu-surface is focused.
isLastElementFocused() => booleanReturns a boolean value indicating if the last focusable element of the menu-surface is focused.
focusFirstElement() => voidFocuses the first focusable element of the menu-surface.
focusLastElement() => voidFocuses the last focusable element of the menu-surface.
getInnerDimensions() => MDCMenuDimensionsReturns an object with the items container width and height.
getAnchorDimensions() => ClientRect \| nullReturns an object with the dimensions and position of the anchor.
getBodyDimensions() => MDCMenuDimensionsReturns an object with width and height of the body, in pixels.
getWindowDimensions() => MDCMenuDimensionsReturns an object with width and height of the viewport, in pixels.
getWindowScroll() => MDCMenuPointReturns an object with the amount the body has been scrolled on the x and y axis.
setPosition(position: Partial<MDCMenuDistance>) => voidSets the position of the menu surface element.
setMaxHeight(value: string) => voidSets max-height style for the menu surface element.

MDCMenuSurfaceFoundation

Method SignatureDescription
setAnchorCorner(corner: Corner) => voidSets the corner that the menu surface will be anchored to. See constants.ts
setAnchorMargin(margin: Partial<MDCMenuDistance>) => voidSets the distance from the anchor point that the menu surface should be shown.
setIsHoisted(isHoisted: boolean) => voidSets whether the menu surface has been hoisted to the body so that the offsets are calculated relative to the page and not the anchor.
setFixedPosition(isFixed: boolean) => voidSets whether the menu surface is using fixed positioning.
setAbsolutePosition(x: number, y: number) => voidSets the absolute x/y position of the menu. Should only be used when the menu is hoisted or using fixed positioning.
handleBodyClick(event: MouseEvent) => voidMethod used as the callback function for the click event.
handleKeydown(event: KeyboardEvent) => voidMethod used as the callback function for the keydown events.
open() => voidOpens the menu surface.
close() => voidCloses the menu.
isOpen() => booleanReturns a boolean indicating whether the menu surface is open.
setQuickOpen(quickOpen: boolean) => voidSets whether the menu surface should open and close without animation when the open/close methods are called.
14.0.0

2 years ago

13.0.0

3 years ago

12.0.0

3 years ago

11.0.0

3 years ago

10.0.0

3 years ago

9.0.0

3 years ago

8.0.0

3 years ago

7.0.0

4 years ago

6.0.0

4 years ago

5.1.0

4 years ago

5.0.0

4 years ago

4.0.0

4 years ago

3.2.0

5 years ago

4.0.0-canary.1

5 years ago

4.0.0-canary.0

5 years ago

4.0.0-alpha.0

5 years ago

3.1.0

5 years ago

3.1.0-alpha.0

5 years ago

3.0.0

5 years ago

3.0.0-alpha.1

5 years ago

3.0.0-alpha.0

5 years ago

2.3.0

5 years ago

1.1.1

5 years ago

1.1.0

5 years ago

1.0.1

5 years ago

1.0.0

5 years ago

1.0.0-1

5 years ago

1.0.0-0

5 years ago

0.44.1

5 years ago

0.44.0

5 years ago

0.43.0

5 years ago

0.42.1

5 years ago

0.42.0

5 years ago

0.41.0

5 years ago

0.40.1

5 years ago

0.40.0

6 years ago

0.39.1

6 years ago

0.39.0

6 years ago

0.39.0-0

6 years ago