1 | @# Menu
|
2 |
|
3 | Menus display lists of interactive items.
|
4 |
|
5 | @reactExample MenuExample
|
6 |
|
7 | @## Dropdowns
|
8 |
|
9 | The `Menu` component by itself simply renders a list of items. To make a
|
10 | dropdown menu, compose a `Menu` as the `content` property of a `Popover`:
|
11 |
|
12 | ```tsx
|
13 | <Popover content={<Menu>...</Menu>} position={Position.RIGHT_TOP}>
|
14 | <Button icon="share" text="Open in..." />
|
15 | </Popover>
|
16 | ```
|
17 |
|
18 | By default, the popover is automatically dismissed when the user clicks a menu
|
19 | item ([Popover docs](#core/components/popover.closing-on-click) have more
|
20 | details). If you want to opt out of this behavior, set
|
21 | `shouldDismissPopover={false}` on a `MenuItem`.
|
22 |
|
23 | In the example below, clicking the menu item labeled "Table" will not dismiss
|
24 | the `Popover`.
|
25 |
|
26 | @reactExample DropdownMenuExample
|
27 |
|
28 | @## Submenus
|
29 |
|
30 | To add a submenu to a `Menu`, simply nest `MenuItem`s within another `MenuItem`.
|
31 | The submenu opens to the right of its parent by default, but will adjust and flip to the left if
|
32 | there is not enough room to the right.
|
33 |
|
34 | ```tsx
|
35 | <Menu>
|
36 | <MenuItem text="Submenu">
|
37 | <MenuItem text="Child one" />
|
38 | <MenuItem text="Child two" />
|
39 | <MenuItem text="Child three" />
|
40 | </MenuItem>
|
41 | </Menu>
|
42 | ```
|
43 |
|
44 | <div class="@ns-callout @ns-intent-warning @ns-icon-warning-sign">
|
45 | <h4 class="@ns-heading">JavaScript only</h4>
|
46 |
|
47 | Submenus are only supported in the React components. They cannot be created with CSS alone because
|
48 | they rely on the [`Popover`](#core/components/popover) component for positioning and transitions.
|
49 |
|
50 | </div>
|
51 |
|
52 | @## Props
|
53 |
|
54 | The `Menu` API includes three stateless React components:
|
55 |
|
56 | * [`Menu`](#core/components/menu.menu)
|
57 | * [`MenuItem`](#core/components/menu.menu-item) (aliased as `Menu.Item`)
|
58 | * [`MenuDivider`](#core/components/menu.menu-divider) (aliased as `Menu.Divider`)
|
59 |
|
60 | ```tsx
|
61 | <Menu>
|
62 | <Menu.Item icon="new-text-box" onClick={this.handleClick} text="New text box" />
|
63 | <Menu.Item icon="new-object" onClick={this.handleClick} text="New object" />
|
64 | <Menu.Item icon="new-link" onClick={this.handleClick} text="New link" />
|
65 | <Menu.Divider />
|
66 | <Menu.Item text="Settings..." icon="cog">
|
67 | <Menu.Item icon="tick" text="Save on edit" />
|
68 | <Menu.Item icon="blank" text="Compile on edit" />
|
69 | </Menu.Item>
|
70 | </Menu>
|
71 | ```
|
72 |
|
73 | @### Menu
|
74 |
|
75 | A `Menu` is a `<ul>` container for menu items and dividers.
|
76 |
|
77 | @interface IMenuProps
|
78 |
|
79 | @### Menu item
|
80 |
|
81 | A `MenuItem` is a single interactive item in a `Menu`.
|
82 |
|
83 | This component renders an `<li>` containing an `<a>`. Make the `MenuItem`
|
84 | interactive by providing the `href`, `target`, and `onClick` props as necessary.
|
85 |
|
86 | Create submenus by nesting `MenuItem`s inside each other as `children`. Use the
|
87 | required `text` prop for `MenuItem` content.
|
88 |
|
89 | @interface IMenuItemProps
|
90 |
|
91 | @### Menu divider
|
92 |
|
93 | Use `MenuDivider` to separate menu sections. Optionally, add a title to the divider.
|
94 |
|
95 | @interface IMenuDividerProps
|
96 |
|
97 | @## CSS
|
98 |
|
99 | Menus can be constructed manually using the HTML markup and `@ns-menu-*` classes below. However, you
|
100 | should use the menu [React components](#core/components/menu.javscript-api) instead wherever possible,
|
101 | as they abstract away the tedious parts of implementing a menu.
|
102 |
|
103 | * Begin with a `ul.@ns-menu`. Each `li` child denotes a single entry in the menu.
|
104 |
|
105 | * Put a `.@ns-menu-item` element inside an `li` to create a clickable entry. Use either `<button>` or
|
106 | `<a>` tags for menu items to denote interactivity.
|
107 |
|
108 | * Add icons to menu items the same way you would to buttons: simply add the appropriate
|
109 | `@ns-icon-<name>` class\*.
|
110 |
|
111 | * Make menu items active with the class `@ns-active` (along with `@ns-intent-*` if suitable).
|
112 |
|
113 | * Make menu items non-interactive with the class `@ns-disabled`.
|
114 |
|
115 | * Wrap menu item text in a `<span>` element for proper alignment. (Note that React automatically
|
116 | does this.)
|
117 |
|
118 | * Add a right-aligned label to a menu item by adding a `span.@ns-menu-item-label` inside the
|
119 | `.@ns-menu-item`, after the content. Add an icon to the label by adding icon classes to the label
|
120 | element (`@ns-icon-standard` size is recommended).
|
121 |
|
122 | * Add a divider between items with `li.@ns-menu-divider`.
|
123 |
|
124 | * If you want the popover to close when the user clicks a menu item, add the class
|
125 | `@ns-popover-dismiss` to any relevant menu items.
|
126 |
|
127 | <small>\* You do not need to add a `@ns-icon-<sizing>` class to menu items—icon sizing is
|
128 | defined as part of `.@ns-menu-item`.</small>
|
129 |
|
130 | <div class="@ns-callout @ns-intent-primary @ns-icon-info-sign">
|
131 |
|
132 | Note that the following examples are `display: inline-block`; you may need to adjust
|
133 | menu width in your own usage.
|
134 |
|
135 | </div>
|
136 |
|
137 | @css menu
|
138 |
|
139 | @### Section headers
|
140 |
|
141 | Add an `li.@ns-menu-header`. Wrap the text in an `<h6>` tag for proper typography and borders.
|
142 |
|
143 | @css menu-header
|