2015-10-29 07:48:59 +03:00
# Menu
2016-03-05 23:20:36 +03:00
2016-11-06 22:18:36 +03:00
A [Menu ](https://material.google.com/components/menus.html ) is a temporary piece of material emitted from a button, an action, a pointer, or another control that contains at least two menu items. Each menu item is a discrete option or action that can affect the app, the view, or selected elements within a view. Menus should not be used as a primary method for navigation within an app. You can compose a menu based on a few subcomponents, same as for Lists.
2015-11-01 14:06:04 +03:00
<!-- example -->
```jsx
2016-03-25 19:03:30 +03:00
import {IconMenu, MenuItem, MenuDivider } from 'react-toolbox/lib/menu';
2016-03-05 23:20:36 +03:00
2015-11-01 14:06:04 +03:00
const MenuTest = () => (
2016-06-10 00:12:29 +03:00
< IconMenu icon = 'more_vert' position = 'topLeft' menuRipple >
2015-11-28 21:46:19 +03:00
< MenuItem value = 'download' icon = 'get_app' caption = 'Download' / >
2015-11-01 14:06:04 +03:00
< MenuItem value = 'help' icon = 'favorite' caption = 'Favorite' / >
2015-11-28 21:46:19 +03:00
< MenuItem value = 'settings' icon = 'open_in_browser' caption = 'Open in app' / >
2015-11-01 14:06:04 +03:00
< MenuDivider / >
< MenuItem value = 'signout' icon = 'delete' caption = 'Delete' disabled / >
< / IconMenu >
);
```
2016-05-29 22:25:49 +03:00
If you want to provide a theme for any of these subcomponents via context, the component key is `RTMenu` .
2015-11-01 14:06:04 +03:00
## Menu
This subcomponent is the default wrapper for a menu and is responsible for the opening behavior. Its properties can affect to the Item children.
2016-05-22 21:15:45 +03:00
### Properties
2016-03-25 19:09:56 +03:00
| Name | Type | Default | Description|
2015-11-01 14:06:04 +03:00
|:-----|:-----|:-----|:-----|
2016-03-25 19:09:56 +03:00
| `active` | `Boolean` | `false` | If true, the menu will be displayed as opened by default.|
| `className` | `String` | `''` | Set a class to give custom styles to the menu wrapper.|
| `onHide` | `Function` | | Callback that will be called when the menu is being hidden. |
| `onSelect` | `Function` | | Callback that will be invoked when a menu item is selected. |
| `onShow` | `Function` | | Callback that will be invoked when the menu is being shown. |
| `outline` | `Boolean` | `true` | If true the menu wrapper will show an outline with a soft shadow. |
2016-06-10 00:12:29 +03:00
| `position` | `String` | `static` | Determine the position of the menu. With `static` value the menu will be always shown, `auto` means that the it will decide the opening direction based on the current position. To force a position use `topLeft` , `topRight` , `bottomLeft` , `bottomRight` . |
2016-03-25 19:09:56 +03:00
| `ripple` | `Boolean` | `true` | If true, the menu items will show a ripple effect on click. |
| `selectable` | `Boolean` | `false` | If true, the menu will keep a value to highlight the active child item. |
| `selected` | `Any` | | Used for selectable menus. Indicates the current selected value so the child item with this value can be highlighted. |
2015-11-01 14:06:04 +03:00
2016-05-22 21:36:06 +03:00
### Theming
| Name | Description|
|:---------|:-----------|
| `active` | Added to the root element when menu is active.|
| `bottomLeft` | Added to the root when position is bottom left.|
| `bottomRight` | Added to the root when position is bottom right.|
| `menu` | Used for the root element of the menu.|
| `menuInner` | Used for the inner wrapper.|
| `outline` | Used to draw the outline.|
| `rippled` | Added to the menu in case if should have ripple.|
| `static` | Added to the root in case its static.|
| `topLeft` | Added to the root when position is top left.|
| `topRight` | Added to the root when position is top right.|
2015-11-01 14:06:04 +03:00
## Icon Menu
As the most usual scenario will be to open the menu from a click in an Icon, we provide this subcomponent implementing this behavior. The `IconMenu` shows an icon and implements a `Menu` under the covers that is shown when is clicked. Some of its properties are transferred to the menu, others to the children:
2016-05-22 21:15:45 +03:00
### Properties
2016-04-07 04:24:31 +03:00
| Name | Type | Default | Description|
2015-11-01 14:06:04 +03:00
|:-----|:-----|:-----|:-----|
2017-08-28 00:17:53 +03:00
| `active` | `Boolean` | `false` | If true, the inner `Menu` component will be active. |
2016-04-07 04:24:31 +03:00
| `className` | `String` | `''` | Set a class to give custom styles to the icon wrapper.|
| `icon` | `String` or `Element` | `more_vert` | Icon font key string or Element to display the opener icon. |
| `iconRipple` | `Boolean` | `true` | If true, the icon will show a ripple when is clicked. |
2017-01-17 15:56:50 +03:00
| `inverse` | `Boolean` | `false` | If true, the neutral colors are inverted. Useful if the icon is over a dark background. |
2016-04-07 04:24:31 +03:00
| `menuRipple` | `Boolean` | `true` | Transferred to the `Menu` component. |
| `onClick` | `Function` | | Callback that will be called when the icon is clicked. |
| `onHide` | `Function` | | Callback that will be called when the menu is being hidden. |
| `onSelect` | `Function` | | Callback that will be invoked when a menu item is selected. |
| `onShow` | `Function` | | Callback that will be invoked when the menu is being shown. |
| `position` | `String` | `auto` | Determines the position of the menu. This property is transferred to the inner `Menu` component. |
| `selectable` | `Boolean` | `false` | If true, the menu will keep a value to highlight the active child item. |
| `selected` | `Any` | | Used for selectable menus. Indicates the current selected value so the child item with this value can be highlighted. |
2015-11-01 14:06:04 +03:00
2016-05-22 21:15:45 +03:00
### Theming
| Name | Description|
|:---------|:-----------|
| `icon` | Used for the icon element.|
| `iconMenu` | Used for the root element of the icon menu.|
2015-11-01 14:06:04 +03:00
## Menu Item
2016-03-25 19:03:30 +03:00
The inner component for menus and describes the content of each option. It behaves in a similar way to List Items but simpler.
2015-11-01 14:06:04 +03:00
2016-05-22 21:43:54 +03:00
### Properties
2016-04-07 04:24:31 +03:00
| Name | Type | Default | Description|
2015-11-01 14:06:04 +03:00
|:-----|:-----|:-----|:-----|
2016-04-07 04:24:31 +03:00
| `caption` | `String` | | The text to include in the menu item. Required.|
| `className` | `String` | `''` | Set a class to give custom styles to the item.|
| `disabled` | `Boolean` | `false` | If true, the item will be displayed as disabled and is not selectable.|
| `icon` | `String` or `Element` | | Icon font key string or Element to display in the right side of the option. |
| `onClick` | `Function` | | Callback that will be called when Component is clicked. |
| `selected` | `Boolean` | `false` | Transferred from the `Menu` component for selectable menus. Indicates if it's the current active option. |
| `shortcut` | `String` | `''` | Displays shortcut text on the right side of the `caption` attribute. |
2015-11-01 14:06:04 +03:00
2016-05-22 21:43:54 +03:00
### Theming
| Name | Description|
|:---------|:-----------|
| `caption` | Used for the caption inside the item.|
| `disabled` | Added to the root element if it's disabled.|
| `icon` | Used for the icon element if exists.|
| `menuItem` | Used as the root class for the component.|
| `selected` | Added to the root element in case it's selected.|
| `shortcut` | Used for the shortcut element if exists.|
2015-11-01 14:06:04 +03:00
## Menu Divider
2016-05-22 21:46:40 +03:00
A very simple component that just displays a separator between options. It has no props and no state or methods, just markup. Also it accepts a single class for the styling which is `menuDivider` .