1 |
|
2 | title: "Top App Bar"
|
3 | layout: detail
|
4 | section: components
|
5 | excerpt: "A container for items such as application title, navigation icon, and action items."
|
6 | iconId: toolbar
|
7 | path: /catalog/top-app-bar/
|
8 | -->
|
9 |
|
10 | # Top app bar
|
11 |
|
12 | The top app bar provides content and actions related to the current screen. It’s used for branding, screen titles, navigation, and actions.
|
13 |
|
14 | There are two types of top app bar:
|
15 |
|
16 | 1. [Regular top app bar](#regular-top-app-bar)
|
17 | 1. [Contextual action bar](#contextual-action-bar)
|
18 |
|
19 | A regular top app bar can transform into a contextual action bar.
|
20 |
|
21 | ![Regular app bar: purple background, white text and icons](images/regular-app-bar.png)
|
22 | ![Contextual app bar: black background, white text and icons](images/contextual-app-bar.png)
|
23 |
|
24 | ## Using the top app bar
|
25 |
|
26 | ### Installation
|
27 |
|
28 | ```
|
29 | npm install @material/top-app-bar
|
30 | ```
|
31 |
|
32 | ### Styles
|
33 |
|
34 | ```scss
|
35 | @use "@material/icon-button";
|
36 | @use "@material/top-app-bar/mdc-top-app-bar";
|
37 |
|
38 | @include icon-button.core-styles;
|
39 | ```
|
40 |
|
41 | ### JavaScript Instantiation
|
42 |
|
43 | ```js
|
44 | import {MDCTopAppBar} from '@material/top-app-bar';
|
45 |
|
46 | // Instantiation
|
47 | const topAppBarElement = document.querySelector('.mdc-top-app-bar');
|
48 | const topAppBar = new MDCTopAppBar(topAppBarElement);
|
49 | ```
|
50 |
|
51 | **Note: See [Importing the JS component](../../docs/importing-js.md) for more information on how to import JavaScript.**
|
52 |
|
53 | ## Regular top app bar
|
54 |
|
55 | The top app bar provides content and actions related to the current screen. It’s used for branding, screen titles, navigation, and actions.
|
56 |
|
57 | ### Regular top app bar example
|
58 |
|
59 | ```html
|
60 | <header class="mdc-top-app-bar">
|
61 | <div class="mdc-top-app-bar__row">
|
62 | <section class="mdc-top-app-bar__section mdc-top-app-bar__section--align-start">
|
63 | <button class="material-icons mdc-top-app-bar__navigation-icon mdc-icon-button" aria-label="Open navigation menu">menu</button>
|
64 | <span class="mdc-top-app-bar__title">Page title</span>
|
65 | </section>
|
66 | <section class="mdc-top-app-bar__section mdc-top-app-bar__section--align-end" role="toolbar">
|
67 | <button class="material-icons mdc-top-app-bar__action-item mdc-icon-button" aria-label="Favorite">favorite</button>
|
68 | <button class="material-icons mdc-top-app-bar__action-item mdc-icon-button" aria-label="Search">search</button>
|
69 | <button class="material-icons mdc-top-app-bar__action-item mdc-icon-button" aria-label="Options">more_vert</button>
|
70 | </section>
|
71 | </div>
|
72 | </header>
|
73 | <main class="mdc-top-app-bar--fixed-adjust">
|
74 | App content
|
75 | </main>
|
76 | ```
|
77 |
|
78 | #### Menu icons
|
79 |
|
80 | Top app bars can contain action items which are placed on the side opposite the navigation icon. You must also attach the `mdc-icon-button` class to both the `mdc-top-app-bar__navigation-icon` and the `mdc-top-app-bar__action-item` elements in order to get the correct styles applied.
|
81 |
|
82 | For further documentation on icons, please see the [mdc-icon-button docs](../mdc-icon-button/README.md).
|
83 |
|
84 | ## Contextual action bar
|
85 |
|
86 | A top app bar can transform into a contextual action bar to provide contextual actions to selected items. For example, upon user selection of photos from a gallery, the top app bar transforms to a contextual app bar with actions related to the selected photos.
|
87 |
|
88 | When a top app bar transforms into a contextual action bar, the following changes occur:
|
89 |
|
90 | * The bar color changes
|
91 | * Navigation icon is replaced with a close icon
|
92 | * Top app bar title text converts to contextual action bar text
|
93 | * Top app bar actions are replaced with contextual actions
|
94 | * Upon closing, the contextual action bar transforms back into a top app bar.
|
95 |
|
96 | ### Contextual action bar example
|
97 |
|
98 | The following example shows a contextual action bar with a contextual title, a close icon, two contextual action icons, and an overflow menu:
|
99 |
|
100 | ```html
|
101 | <header class="mdc-top-app-bar">
|
102 | <div class="mdc-top-app-bar__row">
|
103 | <section class="mdc-top-app-bar__section mdc-top-app-bar__section--align-start">
|
104 | <button class="material-icons mdc-top-app-bar__navigation-icon mdc-icon-button" aria-label="Close">close</button>
|
105 | <span class="mdc-top-app-bar__title">Contextual title</span>
|
106 | </section>
|
107 | <section class="mdc-top-app-bar__section mdc-top-app-bar__section--align-end" role="toolbar">
|
108 | <button class="material-icons mdc-top-app-bar__action-item mdc-icon-button" aria-label="Share">share</button>
|
109 | <button class="material-icons mdc-top-app-bar__action-item mdc-icon-button" aria-label="Delete">delete</button>
|
110 | <button class="material-icons mdc-top-app-bar__action-item mdc-icon-button" aria-label="Open menu">more_vert</button>
|
111 | </section>
|
112 | </div>
|
113 | </header>
|
114 | <main class="mdc-top-app-bar--fixed-adjust">
|
115 | App content
|
116 | </main>
|
117 | ````
|
118 |
|
119 | ## Other Variants
|
120 |
|
121 | ### Short
|
122 |
|
123 | Short top app bars are top app bars that can collapse to the navigation icon side when scrolled.
|
124 |
|
125 | ```html
|
126 | <header class="mdc-top-app-bar mdc-top-app-bar--short">
|
127 | <div class="mdc-top-app-bar__row">
|
128 | <section class="mdc-top-app-bar__section mdc-top-app-bar__section--align-start">
|
129 | <button class="material-icons mdc-top-app-bar__navigation-icon mdc-icon-button">menu</button>
|
130 | <span class="mdc-top-app-bar__title">Title</span>
|
131 | </section>
|
132 | <section class="mdc-top-app-bar__section mdc-top-app-bar__section--align-end" role="toolbar">
|
133 | <button class="material-icons mdc-top-app-bar__action-item mdc-icon-button" aria-label="Bookmark this page">bookmark</button>
|
134 | </section>
|
135 | </div>
|
136 | </header>
|
137 | <main class="mdc-top-app-bar--short-fixed-adjust">
|
138 | App content
|
139 | </main>
|
140 | ```
|
141 |
|
142 | **Note: Short top app bars should be used with no more than 1 action item.**
|
143 |
|
144 | ### Short - always closed
|
145 |
|
146 | Short top app bars can be configured to always appear collapsed by applying the `mdc-top-app-bar--short-collapsed` before instantiating the component :
|
147 |
|
148 | ```html
|
149 | <header class="mdc-top-app-bar mdc-top-app-bar--short mdc-top-app-bar--short-collapsed">
|
150 | ...
|
151 | </header>
|
152 | <main class="mdc-top-app-bar--short-fixed-adjust">
|
153 | App content
|
154 | </main>
|
155 | ```
|
156 |
|
157 | ### Fixed
|
158 |
|
159 | Fixed top app bars stay at the top of the page and elevate above the content when scrolled.
|
160 |
|
161 | ```html
|
162 | <header class="mdc-top-app-bar mdc-top-app-bar--fixed">
|
163 | ...
|
164 | </header>
|
165 | <main class="mdc-top-app-bar--fixed-adjust">
|
166 | App content
|
167 | </main>
|
168 | ```
|
169 |
|
170 | ### Prominent
|
171 |
|
172 | The prominent top app bar is taller.
|
173 |
|
174 | ```html
|
175 | <header class="mdc-top-app-bar mdc-top-app-bar--prominent">
|
176 | ...
|
177 | </header>
|
178 | <main class="mdc-top-app-bar--prominent-fixed-adjust">
|
179 | App content
|
180 | </main>
|
181 | ```
|
182 |
|
183 | ### Dense
|
184 |
|
185 | The dense top app bar is shorter.
|
186 |
|
187 | ```html
|
188 | <header class="mdc-top-app-bar mdc-top-app-bar--dense">
|
189 | ...
|
190 | </header>
|
191 | <main class="mdc-top-app-bar--dense-fixed-adjust">
|
192 | App content
|
193 | </main>
|
194 | ```
|
195 |
|
196 | ## Style customization
|
197 |
|
198 | ### CSS classes
|
199 |
|
200 | Class | Description
|
201 | --- | ---
|
202 | `mdc-top-app-bar` | Mandatory.
|
203 | `mdc-top-app-bar--fixed` | Class used to style the top app bar as a fixed top app bar.
|
204 | `mdc-top-app-bar--fixed-adjust` | Class used to style the content below the top app bar to prevent the top app bar from covering it.
|
205 | `mdc-top-app-bar--prominent` | Class used to style the top app bar as a prominent top app bar.
|
206 | `mdc-top-app-bar--prominent-fixed-adjust` | Class used to style the content below the prominent top app bar to prevent the top app bar from covering it.
|
207 | `mdc-top-app-bar--dense` | Class used to style the top app bar as a dense top app bar.
|
208 | `mdc-top-app-bar--dense-fixed-adjust` | Class used to style the content below the dense top app bar to prevent the top app bar from covering it.
|
209 | `mdc-top-app-bar--dense-prominent-fixed-adjust` | Class used to style the content below the top app bar when styled as both dense and prominent, to prevent the top app bar from covering it.
|
210 | `mdc-top-app-bar--short` | Class used to style the top app bar as a short top app bar.
|
211 | `mdc-top-app-bar--short-collapsed` | Class used to indicate the short top app bar is collapsed.
|
212 | `mdc-top-app-bar--short-fixed-adjust` | Class used to style the content below the short top app bar to prevent the top app bar from covering it.
|
213 |
|
214 | ### Sass mixins
|
215 |
|
216 | Mixin | Description
|
217 | --- | ---
|
218 | `ink-color($color)` | Sets the ink color of the top app bar.
|
219 | `icon-ink-color($color)` | Sets the ink color of the top app bar icons.
|
220 | `fill-color($color)` | Sets the fill color of the top app bar.
|
221 | `fill-color-accessible($color)` | Sets the fill color of the top app bar and automatically sets a high-contrast ink color.
|
222 | `short-shape-radius($radius, $rtl-reflexive)` | Sets the rounded shape to short top app bar variant (when it is collapsed) with given radius size. Set `$rtl-reflexive` to true to flip radius values in RTL context, defaults to true.
|
223 |
|
224 | ## `MDCTopAppBar` properties and methods
|
225 |
|
226 | Method Signature | Description
|
227 | --- | ---
|
228 | `setScrollTarget(target: element) => void` | Sets scroll target to different DOM node (default is window).
|
229 |
|
230 | ### Events
|
231 |
|
232 | Event Name | Event Data Structure | Description
|
233 | --- | --- | ---
|
234 | `MDCTopAppBar:nav` | None | Emits when the navigation icon is clicked.
|
235 |
|
236 | ## Usage within web frameworks
|
237 |
|
238 | If you are using a JavaScript framework, such as React or Angular, you can create a Top App Bar 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](../../docs/integrating-into-frameworks.md).
|
239 |
|
240 | ### `MDCTopAppBarAdapter`
|
241 |
|
242 | Method Signature | Description
|
243 | --- | ---
|
244 | `addClass(className: string) => void` | Adds a class to the root element of the component.
|
245 | `removeClass(className: string) => void` | Removes a class from the root element of the component.
|
246 | `hasClass(className: string) => boolean` | Checks if the root element of the component has the given className.
|
247 | `setStyle(property: string, value: string) => void` | Sets the specified CSS property to the given value on the root element.
|
248 | `getTopAppBarHeight() => number` | Gets the height in px of the top app bar.
|
249 | `getViewportScrollY() => number` | Gets the number of pixels that the content of body is scrolled from the top of the page.
|
250 | `getTotalActionItems() => number` | Gets the number of action items in the top app bar.
|
251 | `notifyNavigationIconClicked() => void` | Emits a custom event `MDCTopAppBar:nav` when the navigation icon is clicked.
|
252 |
|
253 | ### Foundations
|
254 |
|
255 | #### `MDCTopAppBarBaseFoundation`, `MDCTopAppBarFoundation`, `MDCFixedTopAppBarFoundation` and `MDCShortTopAppBarFoundation`
|
256 |
|
257 | All foundations provide the following methods:
|
258 |
|
259 | Method Signature | Description
|
260 | --- | ---
|
261 | `handleTargetScroll() => void` | Handles `scroll` event on specified scrollTarget (defaults to `window`).
|
262 | `handleWindowResize() => void` | Handles `resize` event on window.
|
263 | `handleNavigationClick() => void` | Handles `click` event on navigation icon.
|
264 |
|
265 | #### `MDCShortTopAppBarFoundation`
|
266 |
|
267 | In addition to the methods above, the short variant provides the following public methods and properties:
|
268 |
|
269 | Method Signature | Description
|
270 | --- | ---
|
271 | `setAlwaysCollapsed(value: boolean) => void` | When `value` is `true`, sets the short top app bar to always be collapsed.
|
272 | `getAlwaysCollapsed() => boolean` | Gets if the short top app bar is in the "always collapsed" state.
|
273 |
|
274 | Property | Value Type | Description
|
275 | --- | --- | ---
|
276 | `isCollapsed` | `boolean` (read-only) | Indicates whether the short top app bar is in the collapsed state.
|