1 |
|
2 | title: "Toolbars"
|
3 | layout: detail
|
4 | section: components
|
5 | excerpt: "A container for multiple rows of items such as application title, navigation menu, or tabs."
|
6 | iconId: toolbar
|
7 | path: /catalog/toolbar/
|
8 | -->
|
9 |
|
10 | ## Important - Deprecation Notice
|
11 |
|
12 | The existing `MDCToolbar` component and styles will be removed in a future release. Some of its functionality
|
13 | will be available in the [MDC Top App Bar](../mdc-top-app-bar) package instead. Bugs and feature requests
|
14 | will no longer be accepted for the `mdc-toolbar` package. It is recommended that you migrate to the
|
15 | `mdc-top-app-bar` package to continue to receive new features and updates.
|
16 |
|
17 | # Toolbars
|
18 |
|
19 | MDC Toolbar acts as a container for multiple rows containing items such as
|
20 | application title, navigation menu, and tabs, among other things. Toolbars
|
21 | scroll with content by default, but support fixed behavior as well.
|
22 |
|
23 | When using the **fixed** pattern, a persistent elevation is added to toolbar.
|
24 | When using the **waterfall** pattern, a toolbar will have no elevation when the
|
25 | page is scrolled to the top, and gain elevation when a user begins to scroll
|
26 | down the page. Toolbars also support anchored only last row at the top behavior.
|
27 | For toolbars with this modifier, only the last row will be anchored at the top,
|
28 | while the rest of toolbar scrolls off.
|
29 |
|
30 | Flexible behavior can be added to mdc-toolbar, where the height of the toolbar
|
31 | changes as the user scrolls. Flexible is defined as a modifier class of toolbar
|
32 | but not a standalone component. Toolbars using this modifier will have additional
|
33 | height added to their first rows.
|
34 |
|
35 | ## Installation
|
36 |
|
37 | ```
|
38 | npm install @material/toolbar
|
39 | ```
|
40 |
|
41 | ## Usage
|
42 |
|
43 | ### HTML Structure
|
44 |
|
45 | Wrap the items with `mdc-toolbar` class in the following way:
|
46 |
|
47 | ```html
|
48 | <header class="mdc-toolbar">
|
49 | <div class="mdc-toolbar__row">
|
50 | <section class="mdc-toolbar__section mdc-toolbar__section--align-start">
|
51 | <a href="#" class="material-icons mdc-toolbar__menu-icon">menu</a>
|
52 | <span class="mdc-toolbar__title">Title</span>
|
53 | </section>
|
54 | </div>
|
55 | </header>
|
56 | ```
|
57 |
|
58 | MDC Toolbars can accommodate multiple rows using the wrapper `mdc-toolbar__row`:
|
59 |
|
60 | ```html
|
61 | <header class="mdc-toolbar">
|
62 | <div class="mdc-toolbar__row">
|
63 | <section class="mdc-toolbar__section mdc-toolbar__section--align-start">
|
64 | <a href="#" class="material-icons mdc-toolbar__menu-icon">menu</a>
|
65 | <span class="mdc-toolbar__title">Title</span>
|
66 | </section>
|
67 | </div>
|
68 | <div class="mdc-toolbar__row">
|
69 | ...
|
70 | </div>
|
71 | </header>
|
72 | ```
|
73 |
|
74 | #### Sections
|
75 |
|
76 | Toolbar sections are aligned to the toolbar's center. You can change this
|
77 | behavior by applying `mdc-toolbar__section--align-start` or
|
78 | `mdc-toolbar__section--align-end` to align the sections to the start or the end
|
79 | of the toolbar (respectively).
|
80 |
|
81 | ```html
|
82 | <header class="mdc-toolbar">
|
83 | <div class="mdc-toolbar__row">
|
84 | <section class="mdc-toolbar__section mdc-toolbar__section--align-start">
|
85 | Section aligns to start.
|
86 | </section>
|
87 | <section class="mdc-toolbar__section">
|
88 | Section aligns to center.
|
89 | </section>
|
90 | <section class="mdc-toolbar__section mdc-toolbar__section--align-end">
|
91 | Section aligns to end.
|
92 | </section>
|
93 | </div>
|
94 | </header>
|
95 | ```
|
96 |
|
97 | Toolbar sections are laid out using flexbox. Each section will take up an equal
|
98 | amount of space within the toolbar by default. But you can accommodate very long section (very long title)
|
99 | by adding `mdc-toolbar__section--shrink-to-fit` to other sections.
|
100 |
|
101 | ```html
|
102 | <div class="mdc-toolbar">
|
103 | <div class="mdc-toolbar__row">
|
104 | <section class="mdc-toolbar__section mdc-toolbar__section--align-start">
|
105 | <span class="mdc-toolbar__title">This is a super super super super long title</span>
|
106 | </section>
|
107 | <section class="mdc-toolbar__section mdc-toolbar__section--align-end mdc-toolbar__section--shrink-to-fit">
|
108 | <a class="material-icons search align-icons" aria-label="Search" alt="Search">search</a>
|
109 | </section>
|
110 | </div>
|
111 | </div>
|
112 | ```
|
113 |
|
114 | #### Toolbar title
|
115 |
|
116 | You can use the `mdc-toolbar__title` element to style toolbar text representing
|
117 | a page's title, or an application name.
|
118 |
|
119 | ```html
|
120 | <header class="mdc-toolbar">
|
121 | <div class="mdc-toolbar__row">
|
122 | <section class="mdc-toolbar__section">
|
123 | <span class="mdc-toolbar__title">Title</span>
|
124 | </section>
|
125 | </div>
|
126 | </header>
|
127 | ```
|
128 |
|
129 | #### Toolbar Icons
|
130 |
|
131 | Icons can be added as anchor tags, `span`s, or `button`s to `mdc-toolbar`. There are two types of icons,
|
132 | `mdc-toolbar__menu-icon` represents the left most icon in `mdc-toolbar` usually to the left of `mdc-toolbar__title`.
|
133 | `mdc-toolbar__icon` represents any icons placed on the right side of an `mdc-toolbar`.
|
134 |
|
135 | We recommend using [Material Icons](https://material.io/tools/icons/) from Google Fonts:
|
136 |
|
137 | ```html
|
138 | <head>
|
139 | <link rel="stylesheet" href="https://fonts.googleapis.com/icon?family=Material+Icons">
|
140 | </head>
|
141 | ```
|
142 |
|
143 | However, you can also use SVG, [Font Awesome](https://fontawesome.com/), or any other icon library you wish.
|
144 |
|
145 | When using SVG icons, ensure you wrap the `svg` element in an `a` and include the `mdc-toolbar__icon` class:
|
146 |
|
147 | ```html
|
148 | <a href="#" class="mdc-toolbar__icon">
|
149 | <svg></svg>
|
150 | </a>
|
151 | ```
|
152 |
|
153 | ### Fixed toolbars
|
154 |
|
155 | By default, toolbars scroll with the page content. To keep the toolbar fixed to
|
156 | the top of the screen, add an `mdc-toolbar--fixed` class to the toolbar element.
|
157 |
|
158 | **Adjusting sibling elements of fixed toolbars**
|
159 |
|
160 | When using `mdc-toolbar--fixed`, you need to set the margin of the content to
|
161 | prevent toolbar overlaying your content. You can add the `mdc-toolbar-fixed-adjust`
|
162 | helper class to the toolbar's adjacent sibling element, which will add default
|
163 | `margin-top`.
|
164 |
|
165 | When you are using `mdc-toolbar` with JavaScript, you should assign your content
|
166 | wrapper element to `mdc-toolbar`'s instance property `fixedAdjustElement`. This
|
167 | will make `mdc-toolbar` aware of the wrapper class and adjust the `margin-top`
|
168 | correspondingly.
|
169 |
|
170 | ```html
|
171 | <header class="mdc-toolbar mdc-toolbar--fixed">
|
172 | <div class="mdc-toolbar__row">
|
173 | <section class="mdc-toolbar__section mdc-toolbar__section--align-start">
|
174 | <span class="mdc-toolbar__title">Title</span>
|
175 | </section>
|
176 | </div>
|
177 | </header>
|
178 | <main class="mdc-toolbar-fixed-adjust">
|
179 | <p class="demo-paragraph">
|
180 | A demo paragraph here.
|
181 | </p>
|
182 | </main>
|
183 |
|
184 | // When you are using toolbar with JavaScript
|
185 | <script>
|
186 | var toolbar = mdc.toolbar.MDCToolbar.attachTo(document.querySelector('.mdc-toolbar'));
|
187 | toolbar.fixedAdjustElement = document.querySelector('.mdc-toolbar-fixed-adjust');
|
188 | </script>
|
189 | ```
|
190 |
|
191 | #### Waterfall toolbars (Requires JavaScript)
|
192 |
|
193 | By adding `mdc-toolbar--waterfall` to `mdc-toolbar--fixed`, fixed toolbars become
|
194 | waterfall toolbars. Waterfall toolbar is _initially_ static and has no elevation,
|
195 | and then when the user starts scrolling _becomes_ fixed and _gains_ elevation.
|
196 |
|
197 | ```html
|
198 | <header class="mdc-toolbar mdc-toolbar--fixed mdc-toolbar--waterfall">
|
199 | <div class="mdc-toolbar__row">
|
200 | <section class="mdc-toolbar__section mdc-toolbar__section--align-start">
|
201 | <span class="mdc-toolbar__title">Title</span>
|
202 | </section>
|
203 | </div>
|
204 | </header>
|
205 | <main class="mdc-toolbar-fixed-adjust">
|
206 | <p class="demo-paragraph">
|
207 | A demo paragraph here.
|
208 | </p>
|
209 | </main>
|
210 |
|
211 | <script>
|
212 | var toolbar = mdc.toolbar.MDCToolbar.attachTo(document.querySelector('.mdc-toolbar'));
|
213 | toolbar.fixedAdjustElement = document.querySelector('.mdc-toolbar-fixed-adjust');
|
214 | </script>
|
215 | ```
|
216 |
|
217 | #### Fixed Last Row Toolbar (Requires JavaScript)
|
218 |
|
219 | By adding `mdc-toolbar--fixed-lastrow-only` to `mdc-toolbar--fixed`, fixed toolbars
|
220 | will anchor only the last row to the top.
|
221 |
|
222 | ```html
|
223 | <header class="mdc-toolbar mdc-toolbar--fixed mdc-toolbar--fixed-lastrow-only">
|
224 | <div class="mdc-toolbar__row">
|
225 | <!-- This row will scroll off screen -->
|
226 | </div>
|
227 | <div class="mdc-toolbar__row">
|
228 | <!-- This row will anchor on top of screen -->
|
229 | </div>
|
230 | </header>
|
231 | ```
|
232 |
|
233 | ### Flexible Toolbar (Requires JavaScript)
|
234 |
|
235 | Flexible behavior can be added to mdc-toolbar, whose height changes as the user
|
236 | scrolls. Flexible behavior is highly customizable - we only define the change of
|
237 | flexible space size without making further assumptions. But we do recommend the
|
238 | height of flexible space should be an integral number of `mdc-toolbar__row`
|
239 | height and provide a easier way for user to customize height. Users can adjust the
|
240 | height of flexible space through sass variable `$mdc-toolbar-ratio-to-extend-flexible`
|
241 | or css variable `--mdc-toolbar-ratio-to-extend-flexible`.
|
242 |
|
243 | ```html
|
244 | <header class="mdc-toolbar mdc-toolbar--flexible">
|
245 | <div class="mdc-toolbar__row">
|
246 | ...
|
247 | </div>
|
248 | </header>
|
249 | ```
|
250 |
|
251 | Custom height of flexible space:
|
252 |
|
253 | ```html
|
254 | <style>
|
255 | #my-flexible-header {
|
256 | --mdc-toolbar-ratio-to-extend-flexible: 3;
|
257 | }
|
258 | </style>
|
259 | <header class="mdc-toolbar mdc-toolbar--flexible">
|
260 | <div class="mdc-toolbar__row">
|
261 | ...
|
262 | </div>
|
263 | </header>
|
264 | ```
|
265 |
|
266 | Flexible toolbars emit a `change` custom event with a `detail` object containing
|
267 | `flexibleExpansionRatio` property. The `flexibleExpansionRatio` property is a
|
268 | number from 0-1 representing the _ratio of flexible space that has already been
|
269 | collapsed divided by the total amount of flexible space_.
|
270 |
|
271 | ```javascript
|
272 | toolbar.listen('MDCToolbar:change', function(evt) {
|
273 | var flexibleExpansionRatio = evt.detail.flexibleExpansionRatio;
|
274 | console.log(flexibleExpansionRatio.toFixed(2));
|
275 | });
|
276 |
|
277 | ```
|
278 |
|
279 | For the most common use case of flexible headers, we've defined a **default** behavior:
|
280 | - Flexible has a fixed initial height 4 times the default size of `mdc-toolbar__row`.
|
281 | - When it has `mdc-toolbar--flexible-default-behavior`, it further defines the
|
282 | background and title movement behavior.
|
283 |
|
284 | ```html
|
285 | <style>
|
286 | .mdc-toolbar__row:first-child::after {
|
287 | background-image: url("../images/4-3-2.jpg");
|
288 | background-size: cover;
|
289 | background-position: center;
|
290 | }
|
291 | </style>
|
292 | <header class="mdc-toolbar mdc-toolbar--flexible mdc-toolbar--flexible-default-behavior">
|
293 | <div class="mdc-toolbar__row">
|
294 | ...
|
295 | </div>
|
296 | </header>
|
297 | ```
|
298 |
|
299 | ##### Caveat: Complex animation performance
|
300 |
|
301 | Due to the nature of having to listen for scroll events and mutate height, this
|
302 | may degrade performance in some mobile browsers. For example, combining high
|
303 | resolution images with parallax scrolling could lead to severe performance
|
304 | issues in certain mobile browsers. When implementing patterns like these for a
|
305 | mobile device, ensure that the image is as optimized as possible and carefully
|
306 | test the performance to make sure that it is adequate.
|
307 |
|
308 | ```css
|
309 | .mdc-toolbar__row:first-child::after {
|
310 | background-image: url("../images/4-3.jpg");
|
311 | background-size: cover;
|
312 | background-position: center;
|
313 | }
|
314 | @media (max-width: 599px) {
|
315 | background-image: url("../images/4-3-compressed.jpg");
|
316 | background-position: 0 0;
|
317 | }
|
318 | ```
|
319 |
|
320 | ### RTL Support
|
321 |
|
322 | `mdc-toolbar` is automatically RTL-aware, and will re-position elements whenever
|
323 | it, or its ancestors, has a `dir="rtl"` attribute.
|
324 |
|
325 | ## Classes
|
326 |
|
327 | ### Block
|
328 |
|
329 | The block class is `mdc-toolbar`. This defines the top-level toolbar element.
|
330 |
|
331 | ### Element
|
332 |
|
333 | The component accommodates multiple rows using the wrapper `mdc-toolbar__row`.
|
334 | For each row, it has `mdc-toolbar__section` and `mdc-toolbar__title` elements. You
|
335 | can add multiple sections to toolbar. Refer to Sections and Toolbar title for
|
336 | further details.
|
337 |
|
338 | ### Modifier
|
339 |
|
340 | The provided modifiers are:
|
341 |
|
342 | Class | Description
|
343 | --- | ---
|
344 | `mdc-toolbar--fixed` | Makes toolbar fixed on top and have persistent elevation
|
345 | `mdc-toolbar--waterfall` | Removes fixed toolbar persistent elevation and makes it gain elevation when a user begins to scroll down the page
|
346 | `mdc-toolbar--fixed-lastrow-only` | Makes only last row of fixed toolbar anchored on top
|
347 | `mdc-toolbar--flexible` | Makes first row of toolbar have flexible space
|
348 | `mdc-toolbar__section--align-start` | Makes section align to the start
|
349 | `mdc-toolbar__section--align-end` | Makes section align to the end
|
350 | `mdc-toolbar__section--shrink-to-fit`| Makes section take the width of its content
|
351 |
|
352 | ## Sass Mixins
|
353 |
|
354 | Mixin | Description
|
355 | --- | ---
|
356 | `mdc-toolbar-ink-color($color)` | Sets the ink color of the toolbar
|
357 | `mdc-toolbar-fill-color($color)` | Sets the fill color of the toolbar
|
358 | `mdc-toolbar-fill-color-accessible($color)` | Sets the fill color of the toolbar and automatically sets a high-contrast ink color
|
359 | `mdc-toolbar-icon-ink-color($color)` | Sets the ink color of a toolbar icon
|
360 |
|
361 | ## JS Usage
|
362 |
|
363 | ### Including in code
|
364 |
|
365 | #### ES Module syntax
|
366 |
|
367 | ```javascript
|
368 | import {MDCToolbar, MDCToolbarFoundation} from '@material/toolbar';
|
369 | ```
|
370 |
|
371 | #### CommonJS
|
372 |
|
373 | ```javascript
|
374 | const mdcToolbar = require('@material/toolbar');
|
375 | const MDCToolbar = mdcToolbar.MDCToolbar;
|
376 | const MDCToolbarFoundation = mdcToolbar.MDCToolbarFoundation;
|
377 | ```
|
378 |
|
379 | #### AMD
|
380 |
|
381 | ```javascript
|
382 | require(['/path/to/@material/toolbar'], mdcToolbar => {
|
383 | const MDCToolbar = mdcToolbar.MDCToolbar;
|
384 | const MDCToolbarFoundation = mdcToolbar.MDCToolbarFoundation;
|
385 | });
|
386 | ```
|
387 |
|
388 | #### Global
|
389 |
|
390 | ```javascript
|
391 | const MDCToolbar = mdc.toolbar.MDCToolbar;
|
392 | const MDCToolbarFoundation = mdc.toolbar.MDCToolbarFoundation;
|
393 | ```
|
394 |
|
395 | ### Automatic Instantiation
|
396 |
|
397 | If you do not care about retaining the component instance for the toolbar, simply call `attachTo()`
|
398 | and pass it a DOM element.
|
399 |
|
400 | ```javascript
|
401 | mdc.toolbar.MDCToolbar.attachTo(document.querySelector('.mdc-toolbar'));
|
402 | ```
|
403 |
|
404 | ### Manual Instantiation
|
405 |
|
406 | ```javascript
|
407 | import {MDCToolbar} from '@material/toolbar';
|
408 |
|
409 | const toolbar = new MDCToolbar(document.querySelector('.mdc-toolbar'));
|
410 | ```
|
411 |
|
412 | ### Using the MDCToolbar Foundation Class
|
413 |
|
414 | #### API
|
415 |
|
416 | Method Signature | Description
|
417 | --- | ---
|
418 | `updateAdjustElementStyles() => void` | Sets `AdjustElement` proper `margin-top`.
|
419 |
|
420 | #### Event
|
421 |
|
422 | Event Name | Event Data Structure | Description
|
423 | --- | --- | ---
|
424 | `change` | `MDCToolbarEventDetail` | Emits the ratio of current flexible space to total flexible space height. So when it is minimized, ratio equals to 0 and when it is maximized, ratio equals to 1. See [types.ts](types.ts).
|
425 |
|
426 | #### Adapter
|
427 |
|
428 | Method Signature | Description
|
429 | --- | ---
|
430 | `hasClass(className: string) => boolean` | Checks if the root element of the component has the given className.
|
431 | `addClass(className: string) => void` | Adds a class to the root element of the component.
|
432 | `removeClass(className: string) => void` | Removes a class from the root element of the component.
|
433 | `registerScrollHandler(handler: EventListener) => void` | Registers a handler to be called when user scrolls. Our default implementation adds the handler as a listener to the window's `scroll` event.
|
434 | `deregisterScrollHandler(handler: EventListener) => void` | Unregisters a handler to be called when user scrolls. Our default implementation removes the handler as a listener to the window's `scroll` event.
|
435 | `registerResizeHandler(handler: EventListener) => void` | Registers a handler to be called when the surface (or its viewport) resizes. Our default implementation adds the handler as a listener to the window's `resize` event.
|
436 | `deregisterResizeHandler(handler: EventListener) => void` | Unregisters a handler to be called when the surface (or its viewport) resizes. Our default implementation removes the handler as a listener to the window's `resize` event.
|
437 | `getViewportWidth() => number` | Gets viewport (window) width.
|
438 | `getViewportScrollY() => number` | Gets the number of pixels that the content of body is scrolled upward
|
439 | `getOffsetHeight() => number` | Gets root element `mdc-toolbar` offsetHeight.
|
440 | `getFirstRowElementOffsetHeight() => number` | Gets first row element offsetHeight.
|
441 | `notifyChange(evtData: MDCToolbarEventDetail) => void` | Broadcasts an event with the remaining ratio of flexible space. See [types.ts](types.ts).
|
442 | `setStyle(property: string, value: number) => void` | Sets `mdc-toolbar` style property to provided value.
|
443 | `setStyleForTitleElement(property: string, value: number) => void` | Sets `mdc-toolbar__title` style property to provided value.
|
444 | `setStyleForFlexibleRowElement(property: string, value: number) => void` | Sets flexible row element style property to provided value.
|
445 | `setStyleForFixedAdjustElement(property: string, value: number) => void` | Sets `mdc-toolbar-fixed-adjust` style property to provided value.
|