1# NavDestination
2
3**NavDestination** is the root container of a destination page and represents the content area of the [Navigation](ts-basic-components-navigation.md) component.
4
5> **NOTE**
6>
7> This component is supported since API version 9. Updates will be marked with a superscript to indicate their earliest API version.
8>
9> Since API version 11, this component supports the safe area attribute by default, with the default attribute value being **expandSafeArea([SafeAreaType.SYSTEM], [SafeAreaEdge.TOP, SafeAreaEdge.BOTTOM]))**. You can override this attribute to change the default behavior. In earlier versions, you need to use the [expandSafeArea](ts-universal-attributes-expand-safe-area.md) attribute to implement the safe area feature.
10>
11> The **NavDestination** component must be used in conjunction with the **Navigation** component to act as the root node for the navigation destination page. When used alone, it can only function as a standard container component and does not possess any routing-related attributes or capabilities.
12>
13> If the lifecycle of a page in the middle of the navigation stack changes, the lifecycle of the destination page at the top of the stack before the transition (**onWillShow**, **onShown**, **onHidden**, **onWillDisappear**) and the lifecycle of the destination page after the transition (**onWillShow**, **onShown**, **onHidden**, **onWillDisappear**) are both triggered at the end.
14
15## Child Components
16
17Built-in components and custom components are allowed, with support for ([if/else](../../../quick-start/arkts-rendering-control-ifelse.md), [ForEach](../../../quick-start/arkts-rendering-control-foreach.md), and [LazyForEach](../../../quick-start/arkts-rendering-control-lazyforeach.md)) rendering control.
18
19Number of child components: multiple.
20
21
22## APIs
23
24NavDestination()
25
26**Atomic service API**: This API can be used in atomic services since API version 11.
27
28## Attributes
29
30The [universal attributes](ts-universal-attributes-size.md) are supported.
31
32Avoid setting layout-related attributes such as the position and size. They may result in display issues on the page.
33
34### title
35
36title(value: string | CustomBuilder | NavDestinationCommonTitle | NavDestinationCustomTitle, options?: NavigationTitleOptions)
37
38Sets the page title. When the NavigationCustomTitle type is used to set the height, the **titleMode** attribute does not take effect. When the title string is too long: (1) If no subtitle is set, the string is scaled down, wrapped in two lines, and then clipped with an ellipsis (...); (2) If a subtitle is set, the subtitle is scaled down and then clipped with an ellipsis (...).
39
40**Atomic service API**: This API can be used in atomic services since API version 11.
41
42**System capability**: SystemCapability.ArkUI.ArkUI.Full
43
44**Parameters**
45
46| Name| Type                                                        | Mandatory| Description      |
47| ------ | ------------------------------------------------------------ | ---- | ---------- |
48| value  | string \| [CustomBuilder](ts-types.md#custombuilder8) \| [NavDestinationCommonTitle](#navdestinationcommontitle) \| [NavDestinationCustomTitle](#navdestinationcustomtitle) | Yes  | Page title.|
49| options<sup>12+</sup> | [NavigationTitleOptions](ts-basic-components-navigation.md#navigationtitleoptions11) | No  | Title bar options.|
50
51### hideTitleBar
52
53hideTitleBar(value: boolean)
54
55Specifies whether to hide the title bar.
56
57**Atomic service API**: This API can be used in atomic services since API version 11.
58
59**System capability**: SystemCapability.ArkUI.ArkUI.Full
60
61**Parameters**
62
63| Name| Type   | Mandatory| Description                                                        |
64| ------ | ------- | ---- | ------------------------------------------------------------ |
65| value  | boolean | Yes  | Whether to hide the title bar.<br>Default value: **false**<br>**true**: Hide the title bar.<br>**false**: Display the title bar.|
66
67### mode <sup>11+</sup>
68
69mode(value: NavDestinationMode)
70
71Sets the type of the navigation destination page. Dynamic modification is not supported.
72
73**Atomic service API**: This API can be used in atomic services since API version 12.
74
75**System capability**: SystemCapability.ArkUI.ArkUI.Full
76
77**Parameters**
78
79| Name| Type                                                | Mandatory| Description                                                        |
80| ------ | ---------------------------------------------------- | ---- | ------------------------------------------------------------ |
81| value  | [NavDestinationMode](#navdestinationmode11) | Yes  | Mode of the navigation destination page.<br>Default value: **NavDestinationMode.STANDARD**|
82
83### backButtonIcon<sup>11+</sup>
84
85backButtonIcon(value: ResourceStr | PixelMap | SymbolGlyphModifier)
86
87> **NOTE**
88>
89> The following are not allowed: modify the icon size through the **fontSize** attribute of the **SymbolGlyphModifier** object, change the animation effects through the **effectStrategy** attribute, or change the type of animation effects through the **symbolEffect** attribute.
90
91
92Sets the icon of the back button on the title bar.
93
94**Atomic service API**: This API can be used in atomic services since API version 12.
95
96**System capability**: SystemCapability.ArkUI.ArkUI.Full
97
98**Parameters**
99
100| Name| Type                                                        | Mandatory| Description              |
101| ------ | ------------------------------------------------------------ | ---- | ------------------ |
102| value  | [ResourceStr](ts-types.md#resourcestr) \| [PixelMap](../../apis-image-kit/js-apis-image.md#pixelmap7) \| [SymbolGlyphModifier<sup>12+</sup>](ts-universal-attributes-attribute-modifier.md)  | Yes  | Icon of the back button on the title bar.|
103
104### menus<sup>12+</sup>
105
106menus(value: Array&lt;NavigationMenuItem&gt; | CustomBuilder)
107
108> **NOTE**
109>
110> The following are not allowed: modify the icon size through the **fontSize** attribute of the **SymbolGlyphModifier** object, change the animation effects through the **effectStrategy** attribute, or change the type of animation effects through the **symbolEffect** attribute.
111
112
113Sets the menu items in the upper right corner of the page. If this attribute is not set, no menu item is displayed. When the value type is Array<[NavigationMenuItem](ts-basic-components-navigation.md#navigationmenuitem)&gt;, the menu shows a maximum of three icons in portrait mode and a maximum of five icons in landscape mode, with excess icons (if any) placed under the automatically generated **More** icon.
114
115**Atomic service API**: This API can be used in atomic services since API version 12.
116
117**System capability**: SystemCapability.ArkUI.ArkUI.Full
118
119**Parameters**
120
121| Name| Type                                                        | Mandatory| Description              |
122| ------ | ------------------------------------------------------------ | ---- | ------------------ |
123| value  | Array<[NavigationMenuItem](ts-basic-components-navigation.md#navigationmenuitem)&gt; \| [CustomBuilder](ts-types.md#custombuilder8) | Yes  | Menu items in the upper right corner of the page.|
124
125### ignoreLayoutSafeArea<sup>12+</sup>
126
127ignoreLayoutSafeArea(types?: Array&lt;LayoutSafeAreaType&gt;, edges?: Array&lt;LayoutSafeAreaEdge&gt;)
128
129Ignores the layout safe area by allowing the component to extend into the non-safe areas of the screen.
130
131**Atomic service API**: This API can be used in atomic services since API version 12.
132
133**System capability**: SystemCapability.ArkUI.ArkUI.Full
134
135**Parameters**
136
137| Name| Type                                              | Mandatory| Description                                                        |
138| ------ | -------------------------------------------------- | ---- | ------------------------------------------------------------ |
139| types  | Array <[LayoutSafeAreaType](ts-types.md#layoutsafeareatype12)> | No  | Types of non-safe areas to extend into.<br>Default value:<br>[LayoutSafeAreaType.SYSTEM] |
140| edges  | Array <[LayoutSafeAreaEdge](ts-types.md#layoutsafeareaedge12)> | No  | Edges for expanding the safe area.<br> Default value:<br>[LayoutSafeAreaEdge.TOP, LayoutSafeAreaEdge.BOTTOM]|
141
142>  **NOTE**
143>   
144>  After **LayoutSafeArea** is set:  
145>  When **LayoutSafeAreaType.SYSTEM** is set, the component can extend into the non-safe area if its boundaries overlap with it. For example, if the device's status bar is 100 high, the component must have an absolute vertical offset between 0 and 100 to extend into the non-safe area. 
146>   
147>  If the component extends into the non-safe area, events triggered within that area (such as click events) might be intercepted by the system. This allows the system to prioritize responses to system components such as the status bar.
148
149### systemBarStyle<sup>12+</sup>
150
151systemBarStyle(style: Optional&lt;SystemBarStyle&gt;)
152
153Sets the style of the system status bar when this **NavDestination** page is displayed in the **Navigation** component.
154
155**Atomic service API**: This API can be used in atomic services since API version 12.
156
157**System capability**: SystemCapability.ArkUI.ArkUI.Full
158
159**Parameters**
160
161| Name| Type        | Mandatory| Description              |
162| ------ | -------------- | ---- | ------------------ |
163| style  | Optional&lt;[SystemBarStyle](../js-apis-window.md#systembarstyle12)&gt; | Yes  | Style of the system status bar.|
164
165> **NOTE**
166>
167> 1. The setting takes effect only when the **NavDestination** component is used in conjunction with the **Navigation** component.
168> 2. For other usage restrictions, see the description of [systemBarStyle](ts-basic-components-navigation.md#systembarstyle12) for the **Navigation** component.
169
170## NavDestinationMode<sup>11+</sup>
171
172**Atomic service API**: This API can be used in atomic services since API version 12.
173
174| Name  | Description                                      |
175| ---- | ---------------------------------------- |
176| STANDARD | Standard mode.                      |
177| DIALOG | Dialog mode, in which the navigation destination is transparent by default, adding or removing it from the navigation stack does not affect the lifecycle of the lower-layer navigation destination, and the system transition animation is not supported.   |
178
179## Events
180
181In addition to the [universal events](ts-universal-events-click.md), the following events are supported.
182
183### onShown<sup>10+</sup>
184
185onShown(callback: () =&gt; void)
186
187Called when the navigation destination page is displayed.
188
189**Atomic service API**: This API can be used in atomic services since API version 11.
190
191**System capability**: SystemCapability.ArkUI.ArkUI.Full
192
193### onHidden<sup>10+</sup>
194
195onHidden(callback: () =&gt; void)
196
197Called when the navigation destination page is hidden.
198
199**Atomic service API**: This API can be used in atomic services since API version 11.
200
201**System capability**: SystemCapability.ArkUI.ArkUI.Full
202
203### onWillAppear<sup>12+</sup>
204
205onWillAppear(callback: Callback\<void>)
206
207Called when the navigation destination is about to be mounted. You can change the navigation stack in this callback function, and the change takes effect in the current frame.
208
209**Atomic service API**: This API can be used in atomic services since API version 12.
210
211**System capability**: SystemCapability.ArkUI.ArkUI.Full
212
213### onWillShow<sup>12+</sup>
214
215onWillShow(callback: Callback\<void>)
216
217Called when the navigation destination is about to be displayed.
218
219**Atomic service API**: This API can be used in atomic services since API version 12.
220
221**System capability**: SystemCapability.ArkUI.ArkUI.Full
222
223### onWillHide<sup>12+</sup>
224
225onWillHide(callback: Callback\<void>)
226
227Called when the navigation destination is about to be hidden.
228
229**Atomic service API**: This API can be used in atomic services since API version 12.
230
231**System capability**: SystemCapability.ArkUI.ArkUI.Full
232
233### onWillDisappear<sup>12+</sup>
234
235onWillDisappear(callback: Callback\<void>)
236
237Called when the navigation destination is about to be unmounted (or when the transition animation, if any, is about to start).
238
239**Atomic service API**: This API can be used in atomic services since API version 12.
240
241**System capability**: SystemCapability.ArkUI.ArkUI.Full
242
243### onBackPressed<sup>10+</sup>
244
245onBackPressed(callback: () =&gt; boolean)
246
247This callback takes effect when there is one or more entries in the navigation stack bound to the **Navigation** component. Called when the back button is pressed.
248
249The value **true** means that the back button logic is overridden, and **false** means that the previous page is displayed.
250
251**Atomic service API**: This API can be used in atomic services since API version 11.
252
253**System capability**: SystemCapability.ArkUI.ArkUI.Full
254
255### onReady<sup>11+</sup>
256
257onReady(callback: [Callback](../../apis-basic-services-kit/js-apis-base.md#callback)<[NavDestinationContext](#navdestinationcontext11)>)
258
259Called when the **NavDestination** component is about to build a child component.
260
261**Atomic service API**: This API can be used in atomic services since API version 11.
262
263**System capability**: SystemCapability.ArkUI.ArkUI.Full
264
265## NavDestinationCommonTitle
266
267**Atomic service API**: This API can be used in atomic services since API version 11.
268
269**System capability**: SystemCapability.ArkUI.ArkUI.Full
270
271| Name  | Type    | Mandatory  | Description    |
272| ---- | ------ | ---- | ------ |
273| main | string | Yes   | Main title.|
274| sub  | string | Yes   | Subtitle.|
275
276## NavDestinationCustomTitle
277
278**Atomic service API**: This API can be used in atomic services since API version 11.
279
280**System capability**: SystemCapability.ArkUI.ArkUI.Full
281
282| Name     | Type                                      | Mandatory  | Description      |
283| ------- | ---------------------------------------- | ---- | -------- |
284| builder | [CustomBuilder](ts-types.md#custombuilder8) | Yes   | Content of the title bar.|
285| height  | [TitleHeight](ts-basic-components-navigation.md#titleheight9) \| [Length](ts-types.md#length) | Yes   | Height of the title bar.|
286
287## NavDestinationContext<sup>11+</sup>
288
289| Name  | Type    | Mandatory  |  Description    |
290| ---- | ------ | ----- | ------ |
291| pathInfo | [NavPathInfo](ts-basic-components-navigation.md#navpathinfo10) | Yes| Path information of the navigation destination page.<br>**Atomic service API**: This API can be used in atomic services since API version 11.|
292| pathStack  | [NavPathStack](ts-basic-components-navigation.md#navpathstack10) | Yes| Page stack where the current navigation destination page is located.<br>**Atomic service API**: This API can be used in atomic services since API version 11.|
293| navDestinationId<sup>12+</sup> | string | No| Unique ID of the current navigation destination page, which is automatically generated by the system and is irrelevant to the universal attribute **id** of the component.<br>**Atomic service API**: This API can be used in atomic services since API version 12.|
294
295### getConfigInRouteMap<sup>12+</sup>
296
297getConfigInRouteMap(): RouteMapConfig |undefined
298
299**Atomic service API**: This API can be used in atomic services since API version 12.
300
301**System capability**: SystemCapability.ArkUI.ArkUI.Full
302
303**Return value**
304
305| Type| Description|
306| --- | --- |
307| [RouteMapConfig](#routemapconfig12) | Route map configuration of the current page.|
308| undefined | **undefined**, returned when the page is not configured through the route table.|
309
310## RouteMapConfig<sup>12+</sup>
311
312**Atomic service API**: This API can be used in atomic services since API version 12.
313
314| Name  | Type  | Description|
315| ----  | ---   | ----- |
316| name  | string | Page name.|
317| pageSourceFile| string | Path of the page in the current package.|
318| data | object | Custom data of the page.|
319
320## Example
321
322For details, see [Example in Navigation](ts-basic-components-navigation.md#example-1).
323