1# Menu
2
3The **Menu** component is a vertical list of items presented to the user.
4
5> **NOTE**
6>
7> - This component is supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version.
8>
9> - The **Menu** component must be used together with the [bindMenu](ts-universal-attributes-menu.md#bindmenu) or [bindContextMenu](ts-universal-attributes-menu.md#bindcontextmenu8) method. It does not work when used alone.
10
11## Child Components
12
13This component contains the [MenuItem](ts-basic-components-menuitem.md) and [MenuItemGroup](ts-basic-components-menuitemgroup.md) child components.
14
15## APIs
16
17Menu()
18
19Creates a fixed container for a menu. This API does not have any parameters.
20
21> **NOTE**
22> Rules for calculating the width of menus and menu items:
23>
24> During the layout, the width of each menu item is expected to be the same. If a child component has its width set, the [size calculation rule](ts-universal-attributes-size.md#constraintsize) prevails.
25>
26> If the width is not set, the **Menu** component sets the default width of two columns for the **MenuItem** and **MenuItemGroup** child components. If a menu item's content area is wider than two columns, the **Menu** component automatically expands the menu item content area.
27>
28> When the width is set, the **Menu** component sets the **MenuItem** and **MenuItemGroup** child components to the fixed width (set width minus the padding).
29
30**Atomic service API**: This API can be used in atomic services since API version 11.
31
32## subMenuExpandingMode<sup>12+</sup>
33
34Enumerates the submenu expanding modes.
35
36**Atomic service API**: This API can be used in atomic services since API version 12.
37
38| Name          | Description                               |
39|--------------|-----------------------------------|
40| SIDE_EXPAND  | Default mode. Submenus are expanded on the side on the same plane.           |
41| EMBEDDED_EXPAND | Embedded mode. Submenus are expanded while embedded within the main menu.             |
42| STACK_EXPAND | Stack mode. Submenus are expanded above the main menu. |
43
44## Attributes
45
46In addition to the [universal attributes](ts-universal-attributes-size.md), the following attributes are supported.
47
48### fontSize<sup>(deprecated)</sup>
49
50fontSize(value: Length)
51
52Sets the size of all text within the menu.
53
54This API is deprecated since API version 10. You are advised to use [font](#font10) instead.
55
56**System capability**: SystemCapability.ArkUI.ArkUI.Full
57
58**Parameters**
59
60| Name | Type                        | Mandatory | Description                                                    |
61| ------ | ---------------------------- | ---- | -------------------------------------------------------- |
62| value  | [Length](ts-types.md#length) | Yes  | Size of all text within the menu. If the value of the Length type is a number, the unit is fp. |
63
64### font<sup>10+</sup>
65
66font(value: Font)
67
68Sets the size of all text within the menu.
69
70**Atomic service API**: This API can be used in atomic services since API version 11.
71
72**System capability**: SystemCapability.ArkUI.ArkUI.Full
73
74**Parameters**
75
76| Name | Type                    | Mandatory | Description                  |
77| ------ | ------------------------ | ---- | ---------------------- |
78| value  | [Font](ts-types.md#font) | Yes  | Size of all text within the menu. |
79
80### fontColor<sup>10+</sup>
81
82fontColor(value: ResourceColor)
83
84Sets the font color of all text within the menu.
85
86**Atomic service API**: This API can be used in atomic services since API version 11.
87
88**System capability**: SystemCapability.ArkUI.ArkUI.Full
89
90**Parameters**
91
92| Name | Type                                      | Mandatory | Description                  |
93| ------ | ------------------------------------------ | ---- | ---------------------- |
94| value  | [ResourceColor](ts-types.md#resourcecolor) | Yes  | Font color of all text within the menu. |
95
96### radius<sup>10+</sup>
97
98radius(value: Dimension | BorderRadiuses)
99
100Sets the radius of the menu border corners.
101
102**Atomic service API**: This API can be used in atomic services since API version 11.
103
104**System capability**: SystemCapability.ArkUI.ArkUI.Full
105
106**Parameters**
107
108| Name | Type                                                        | Mandatory | Description                                                        |
109| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
110| value  | [Dimension](ts-types.md#dimension10) \| [BorderRadiuses](ts-types.md#borderradiuses9) | Yes  | Radius of the menu border corners.<br> The default value follows the theme.<br> Since API version 12, if the sum of the two maximum corner radii in the horizontal direction exceeds the menu's width, or if the sum of the two maximum corner radii in the vertical direction exceeds the menu's height, the default corner radius will be used for all four corners of the menu. |
111
112### width<sup>10+</sup>
113
114width(value: Length)
115
116Sets the border width of the menu. The minimum width is 64 vp.
117
118**Widget capability**: This API can be used in ArkTS widgets since API version 10.
119
120**System capability**: SystemCapability.ArkUI.ArkUI.Full
121
122**Parameters**
123
124| Name | Type                        | Mandatory | Description          |
125| ------ | ---------------------------- | ---- | -------------- |
126| value  | [Length](ts-types.md#length) | Yes  | Border width of the menu. |
127
128### menuItemDivider<sup>12+</sup>
129
130menuItemDivider(options: DividerStyleOptions | undefined)
131
132Sets the style of the menu item divider. If this attribute is not set, the divider will not be displayed.
133
134If the sum of **startMargin** and **endMargin** exceeds the component width, both **startMargin** and **endMargin** will be set to **0**.
135
136**Atomic service API**: This API can be used in atomic services since API version 12.
137
138**System capability**: SystemCapability.ArkUI.ArkUI.Full
139
140**Parameters**
141
142| Name    | Type                                                    | Mandatory        | Description          |
143|---------|--------------------------------------------------------|------------| -------------- |
144| options | [DividerStyleOptions](ts-types.md#dividerstyleoptions12) \|  undefined | Yes  | Style of the menu item divider.<br>- **strokeWidth**: stroke width of the divider.<br>- **color**: color of the divider.<br>- **startMargin**: distance between the divider and the start edge of the menu item.<br>- **endMargin**: distance between the divider and the end edge of the menu item. |
145
146### menuItemGroupDivider<sup>12+</sup>
147
148menuItemGroupDivider(options: DividerStyleOptions | undefined)
149
150Sets the style of the top and bottom dividers for the menu item group. If this attribute is not set, the dividers will be displayed by default.
151
152**Atomic service API**: This API can be used in atomic services since API version 12.
153
154**System capability**: SystemCapability.ArkUI.ArkUI.Full
155
156**Parameters**
157
158| Name    | Type                                                    | Mandatory        | Description          |
159|---------|--------------------------------------------------------|------------| -------------- |
160| options | [DividerStyleOptions](ts-types.md#dividerstyleoptions12) \|  undefined | Yes  | Style of the top and bottom dividers for the menu item group.<br>- **strokeWidth**: stroke width of the divider. The default value is 1 px.<br>- **color**: color of the divider. The default value is **#33000000**.<br>- **startMargin**: distance between the divider and the start edge of the menu item group. The default value is **16**.<br>- **endMargin**: distance between the divider and the end edge of the menu item group. The default value is **16**. |
161
162### subMenuExpandingMode<sup>12+</sup>
163
164subMenuExpandingMode(mode: SubMenuExpandingMode)
165
166Sets the submenu expanding mode of the menu.
167
168**Atomic service API**: This API can be used in atomic services since API version 12.
169
170**System capability**: SystemCapability.ArkUI.ArkUI.Full
171
172**Parameters**
173
174| Name | Type                        | Mandatory | Description          |
175| ------ | ---------------------------- | ---- |--------------|
176| mode  | SubMenuExpandingMode | Yes  | Submenu expanding mode of the menu. |
177
178## Example
179
180### Example 1
181
182```ts
183@Entry
184@Component
185struct Index {
186  @State select: boolean = true
187  private iconStr: ResourceStr = $r("app.media.view_list_filled")
188  private iconStr2: ResourceStr = $r("app.media.arrow_right_filled")
189
190  @Builder
191  SubMenu() {
192    Menu() {
193      MenuItem({ content: "Copy", labelInfo: "Ctrl+C" })
194      MenuItem({ content: "Paste", labelInfo: "Ctrl+V" })
195    }
196  }
197
198  @Builder
199  MyMenu(){
200    Menu() {
201      MenuItem({ startIcon: $r("app.media.icon"), content: "Menu item" })
202      MenuItem({ startIcon: $r("app.media.icon"), content: "Menu item" })
203        .enabled(false)
204      MenuItem({
205        startIcon: this.iconStr,
206        content: "Menu item",
207        endIcon: this.iconStr2,
208        builder: ():void=>this.SubMenu()
209      })
210      MenuItemGroup({ header: 'Subtitle' }) {
211        MenuItem({
212          startIcon: this.iconStr,
213          content: "Menu item",
214          endIcon: this.iconStr2,
215          builder: ():void=>this.SubMenu()
216        })
217        MenuItem({
218          startIcon: $r("app.media.app_icon"),
219          content: "Menu item",
220          endIcon: this.iconStr2,
221          builder: ():void=>this.SubMenu()
222        })
223      }
224      MenuItem({
225        startIcon: this.iconStr,
226        content: "Menu item",
227      })
228    }
229  }
230
231  build() {
232    Row() {
233      Column() {
234        Text('click to show menu')
235          .fontSize(50)
236          .fontWeight(FontWeight.Bold)
237      }
238      .bindMenu(this.MyMenu)
239      .width('100%')
240    }
241    .height('100%')
242  }
243}
244```
245
246![menu1](figures/menu1.png)
247
248### Example 2
249
250This example demonstrates a regular menu (using symbol-type icons).
251
252```ts
253// xxx.ets
254import { SymbolGlyphModifier } from '@kit.ArkUI';
255
256@Entry
257@Component
258struct Index {
259  @State startIconModifier: SymbolGlyphModifier = new SymbolGlyphModifier($r('sys.symbol.ohos_mic')).fontSize('24vp');
260  @State endIconModifier: SymbolGlyphModifier = new SymbolGlyphModifier($r('sys.symbol.ohos_trash')).fontSize('24vp');
261  @State selectIconModifier: SymbolGlyphModifier =
262    new SymbolGlyphModifier($r('sys.symbol.checkmark')).fontSize('24vp');
263  @State select: boolean = true;
264
265  @Builder
266  SubMenu() {
267    Menu() {
268      MenuItem({ content: "Copy", labelInfo: "Ctrl+C" })
269      MenuItem({ content: "Paste", labelInfo: "Ctrl+V" })
270    }
271  }
272
273  @Builder
274  MyMenu() {
275    Menu() {
276      MenuItem({ symbolStartIcon: this.startIconModifier, content: "Menu item" })
277      MenuItem({ symbolStartIcon: this.startIconModifier, content: "Menu item" })
278        .enabled(false)
279      MenuItem({
280        symbolStartIcon: this.startIconModifier,
281        content: "Menu item",
282        symbolEndIcon: this.endIconModifier,
283        builder: (): void => this.SubMenu()
284      })
285      MenuItemGroup({ header: 'Subtitle' }) {
286        MenuItem({
287          symbolStartIcon: this.startIconModifier,
288          content: "Menu item",
289          symbolEndIcon: this.endIconModifier,
290          builder: (): void => this.SubMenu()
291        })
292        MenuItem({
293          symbolStartIcon: this.startIconModifier,
294          content: "Menu item",
295          symbolEndIcon: this.endIconModifier,
296          builder: (): void => this.SubMenu()
297        })
298      }
299      MenuItem({
300        content: "Menu item",
301      }).selected(this.select).selectIcon(this.selectIconModifier)
302    }
303  }
304
305  build() {
306    Row() {
307      Column() {
308        Text('click to show menu')
309          .fontSize(50)
310          .fontWeight(FontWeight.Bold)
311      }
312      .bindMenu(this.MyMenu)
313      .width('100%')
314    }
315    .height('100%')
316  }
317}
318```
319
320![en-us_image_0000001174582862](figures/normal-symbol.jpg)
321