Important - Deprecation Notice
The existing MDCToolbar
component and styles will be removed in a future release. Some of its functionality
will be available in the MDC Top App Bar package instead. Bugs and feature requests
will no longer be accepted for the mdc-toolbar
package. It is recommended that you migrate to the
mdc-top-app-bar
package to continue to receive new features and updates.
Toolbars
MDC Toolbar acts as a container for multiple rows containing items such as
application title, navigation menu, and tabs, among other things. Toolbars
scroll with content by default, but support fixed behavior as well.
When using the fixed pattern, a persistent elevation is added to toolbar.
When using the waterfall pattern, a toolbar will have no elevation when the
page is scrolled to the top, and gain elevation when a user begins to scroll
down the page. Toolbars also support anchored only last row at the top behavior.
For toolbars with this modifier, only the last row will be anchored at the top,
while the rest of toolbar scrolls off.
Flexible behavior can be added to mdc-toolbar, where the height of the toolbar
changes as the user scrolls. Flexible is defined as a modifier class of toolbar
but not a standalone component. Toolbars using this modifier will have additional
height added to their first rows.
Installation
npm install @material/toolbar
Usage
HTML Structure
Wrap the items with mdc-toolbar
class in the following way:
<header class="mdc-toolbar">
<div class="mdc-toolbar__row">
<section class="mdc-toolbar__section mdc-toolbar__section--align-start">
<a href="#" class="material-icons mdc-toolbar__menu-icon">menu</a>
<span class="mdc-toolbar__title">Title</span>
</section>
</div>
</header>
MDC Toolbars can accommodate multiple rows using the wrapper mdc-toolbar__row
:
<header class="mdc-toolbar">
<div class="mdc-toolbar__row">
<section class="mdc-toolbar__section mdc-toolbar__section--align-start">
<a href="#" class="material-icons mdc-toolbar__menu-icon">menu</a>
<span class="mdc-toolbar__title">Title</span>
</section>
</div>
<div class="mdc-toolbar__row">
...
</div>
</header>
Sections
Toolbar sections are aligned to the toolbar's center. You can change this
behavior by applying mdc-toolbar__section--align-start
or
mdc-toolbar__section--align-end
to align the sections to the start or the end
of the toolbar (respectively).
<header class="mdc-toolbar">
<div class="mdc-toolbar__row">
<section class="mdc-toolbar__section mdc-toolbar__section--align-start">
Section aligns to start.
</section>
<section class="mdc-toolbar__section">
Section aligns to center.
</section>
<section class="mdc-toolbar__section mdc-toolbar__section--align-end">
Section aligns to end.
</section>
</div>
</header>
Toolbar sections are laid out using flexbox. Each section will take up an equal
amount of space within the toolbar by default. But you can accommodate very long section (very long title)
by adding mdc-toolbar__section--shrink-to-fit
to other sections.
<div class="mdc-toolbar">
<div class="mdc-toolbar__row">
<section class="mdc-toolbar__section mdc-toolbar__section--align-start">
<span class="mdc-toolbar__title">This is a super super super super long title</span>
</section>
<section class="mdc-toolbar__section mdc-toolbar__section--align-end mdc-toolbar__section--shrink-to-fit">
<a class="material-icons search align-icons" aria-label="Search" alt="Search">search</a>
</section>
</div>
</div>
Toolbar title
You can use the mdc-toolbar__title
element to style toolbar text representing
a page's title, or an application name.
<header class="mdc-toolbar">
<div class="mdc-toolbar__row">
<section class="mdc-toolbar__section">
<span class="mdc-toolbar__title">Title</span>
</section>
</div>
</header>
Toolbar Icons
Icons can be added as anchor tags, span
s, or button
s to mdc-toolbar
. There are two types of icons,
mdc-toolbar__menu-icon
represents the left most icon in mdc-toolbar
usually to the left of mdc-toolbar__title
.
mdc-toolbar__icon
represents any icons placed on the right side of an mdc-toolbar
.
We recommend using Material Icons from Google Fonts:
<head>
<link rel="stylesheet" href="https://fonts.googleapis.com/icon?family=Material+Icons">
</head>
However, you can also use SVG, Font Awesome, or any other icon library you wish.
When using SVG icons, ensure you wrap the svg
element in an a
and include the mdc-toolbar__icon
class:
<a href="#" class="mdc-toolbar__icon">
<svg></svg>
</a>
Fixed toolbars
By default, toolbars scroll with the page content. To keep the toolbar fixed to
the top of the screen, add an mdc-toolbar--fixed
class to the toolbar element.
Adjusting sibling elements of fixed toolbars
When using mdc-toolbar--fixed
, you need to set the margin of the content to
prevent toolbar overlaying your content. You can add the mdc-toolbar-fixed-adjust
helper class to the toolbar's adjacent sibling element, which will add default
margin-top
.
When you are using mdc-toolbar
with JavaScript, you should assign your content
wrapper element to mdc-toolbar
's instance property fixedAdjustElement
. This
will make mdc-toolbar
aware of the wrapper class and adjust the margin-top
correspondingly.
<header class="mdc-toolbar mdc-toolbar--fixed">
<div class="mdc-toolbar__row">
<section class="mdc-toolbar__section mdc-toolbar__section--align-start">
<span class="mdc-toolbar__title">Title</span>
</section>
</div>
</header>
<main class="mdc-toolbar-fixed-adjust">
<p class="demo-paragraph">
A demo paragraph here.
</p>
</main>
// When you are using toolbar with JavaScript
<script>
var toolbar = mdc.toolbar.MDCToolbar.attachTo(document.querySelector('.mdc-toolbar'));
toolbar.fixedAdjustElement = document.querySelector('.mdc-toolbar-fixed-adjust');
</script>
Waterfall toolbars (Requires JavaScript)
By adding mdc-toolbar--waterfall
to mdc-toolbar--fixed
, fixed toolbars become
waterfall toolbars. Waterfall toolbar is initially static and has no elevation,
and then when the user starts scrolling becomes fixed and gains elevation.
<header class="mdc-toolbar mdc-toolbar--fixed mdc-toolbar--waterfall">
<div class="mdc-toolbar__row">
<section class="mdc-toolbar__section mdc-toolbar__section--align-start">
<span class="mdc-toolbar__title">Title</span>
</section>
</div>
</header>
<main class="mdc-toolbar-fixed-adjust">
<p class="demo-paragraph">
A demo paragraph here.
</p>
</main>
<script>
var toolbar = mdc.toolbar.MDCToolbar.attachTo(document.querySelector('.mdc-toolbar'));
toolbar.fixedAdjustElement = document.querySelector('.mdc-toolbar-fixed-adjust');
</script>
Fixed Last Row Toolbar (Requires JavaScript)
By adding mdc-toolbar--fixed-lastrow-only
to mdc-toolbar--fixed
, fixed toolbars
will anchor only the last row to the top.
<header class="mdc-toolbar mdc-toolbar--fixed mdc-toolbar--fixed-lastrow-only">
<div class="mdc-toolbar__row">
</div>
<div class="mdc-toolbar__row">
</div>
</header>
Flexible Toolbar (Requires JavaScript)
Flexible behavior can be added to mdc-toolbar, whose height changes as the user
scrolls. Flexible behavior is highly customizable - we only define the change of
flexible space size without making further assumptions. But we do recommend the
height of flexible space should be an integral number of mdc-toolbar__row
height and provide a easier way for user to customize height. Users can adjust the
height of flexible space through sass variable $mdc-toolbar-ratio-to-extend-flexible
or css variable --mdc-toolbar-ratio-to-extend-flexible
.
<header class="mdc-toolbar mdc-toolbar--flexible">
<div class="mdc-toolbar__row">
...
</div>
</header>
Custom height of flexible space:
<style>
#my-flexible-header {
--mdc-toolbar-ratio-to-extend-flexible: 3;
}
</style>
<header class="mdc-toolbar mdc-toolbar--flexible">
<div class="mdc-toolbar__row">
...
</div>
</header>
Flexible toolbars emit a change
custom event with a detail
object containing
flexibleExpansionRatio
property. The flexibleExpansionRatio
property is a
number from 0-1 representing the ratio of flexible space that has already been
collapsed divided by the total amount of flexible space.
toolbar.listen('MDCToolbar:change', function(evt) {
var flexibleExpansionRatio = evt.detail.flexibleExpansionRatio;
console.log(flexibleExpansionRatio.toFixed(2));
});
For the most common use case of flexible headers, we've defined a default behavior:
- Flexible has a fixed initial height 4 times the default size of
mdc-toolbar__row
. - When it has
mdc-toolbar--flexible-default-behavior
, it further defines the
background and title movement behavior.
<style>
.mdc-toolbar__row:first-child::after {
background-image: url("../images/4-3-2.jpg");
background-size: cover;
background-position: center;
}
</style>
<header class="mdc-toolbar mdc-toolbar--flexible mdc-toolbar--flexible-default-behavior">
<div class="mdc-toolbar__row">
...
</div>
</header>
Caveat: Complex animation performance
Due to the nature of having to listen for scroll events and mutate height, this
may degrade performance in some mobile browsers. For example, combining high
resolution images with parallax scrolling could lead to severe performance
issues in certain mobile browsers. When implementing patterns like these for a
mobile device, ensure that the image is as optimized as possible and carefully
test the performance to make sure that it is adequate.
.mdc-toolbar__row:first-child::after {
background-image: url("../images/4-3.jpg");
background-size: cover;
background-position: center;
}
@media (max-width: 599px) {
background-image: url("../images/4-3-compressed.jpg");
background-position: 0 0;
}
RTL Support
mdc-toolbar
is automatically RTL-aware, and will re-position elements whenever
it, or its ancestors, has a dir="rtl"
attribute.
Classes
Block
The block class is mdc-toolbar
. This defines the top-level toolbar element.
Element
The component accommodates multiple rows using the wrapper mdc-toolbar__row
.
For each row, it has mdc-toolbar__section
and mdc-toolbar__title
elements. You
can add multiple sections to toolbar. Refer to Sections and Toolbar title for
further details.
Modifier
The provided modifiers are:
Class | Description |
---|
mdc-toolbar--fixed | Makes toolbar fixed on top and have persistent elevation |
mdc-toolbar--waterfall | Removes fixed toolbar persistent elevation and makes it gain elevation when a user begins to scroll down the page |
mdc-toolbar--fixed-lastrow-only | Makes only last row of fixed toolbar anchored on top |
mdc-toolbar--flexible | Makes first row of toolbar have flexible space |
mdc-toolbar__section--align-start | Makes section align to the start |
mdc-toolbar__section--align-end | Makes section align to the end |
mdc-toolbar__section--shrink-to-fit | Makes section take the width of its content |
Sass Mixins
Mixin | Description |
---|
mdc-toolbar-ink-color($color) | Sets the ink color of the toolbar |
mdc-toolbar-fill-color($color) | Sets the fill color of the toolbar |
mdc-toolbar-fill-color-accessible($color) | Sets the fill color of the toolbar and automatically sets a high-contrast ink color |
mdc-toolbar-icon-ink-color($color) | Sets the ink color of a toolbar icon |
JS Usage
Including in code
ES Module syntax
import {MDCToolbar, MDCToolbarFoundation} from '@material/toolbar';
CommonJS
const mdcToolbar = require('@material/toolbar');
const MDCToolbar = mdcToolbar.MDCToolbar;
const MDCToolbarFoundation = mdcToolbar.MDCToolbarFoundation;
AMD
require(['/path/to/@material/toolbar'], mdcToolbar => {
const MDCToolbar = mdcToolbar.MDCToolbar;
const MDCToolbarFoundation = mdcToolbar.MDCToolbarFoundation;
});
Global
const MDCToolbar = mdc.toolbar.MDCToolbar;
const MDCToolbarFoundation = mdc.toolbar.MDCToolbarFoundation;
Automatic Instantiation
If you do not care about retaining the component instance for the toolbar, simply call attachTo()
and pass it a DOM element.
mdc.toolbar.MDCToolbar.attachTo(document.querySelector('.mdc-toolbar'));
Manual Instantiation
import {MDCToolbar} from '@material/toolbar';
const toolbar = new MDCToolbar(document.querySelector('.mdc-toolbar'));
Using the MDCToolbar Foundation Class
API
Method Signature | Description |
---|
updateAdjustElementStyles() => void | Sets AdjustElement proper margin-top . |
Event
Event Name | Event Data Structure | Description |
---|
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. |
Adapter
Method Signature | Description |
---|
hasClass(className: string) => boolean | Checks if the root element of the component has the given className. |
addClass(className: string) => void | Adds a class to the root element of the component. |
removeClass(className: string) => void | Removes a class from the root element of the component. |
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. |
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. |
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. |
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. |
getViewportWidth() => number | Gets viewport (window) width. |
getViewportScrollY() => number | Gets the number of pixels that the content of body is scrolled upward |
getOffsetHeight() => number | Gets root element mdc-toolbar offsetHeight. |
getFirstRowElementOffsetHeight() => number | Gets first row element offsetHeight. |
notifyChange(evtData: MDCToolbarEventDetail) => void | Broadcasts an event with the remaining ratio of flexible space. See types.ts. |
setStyle(property: string, value: number) => void | Sets mdc-toolbar style property to provided value. |
setStyleForTitleElement(property: string, value: number) => void | Sets mdc-toolbar__title style property to provided value. |
setStyleForFlexibleRowElement(property: string, value: number) => void | Sets flexible row element style property to provided value. |
setStyleForFixedAdjustElement(property: string, value: number) => void | Sets mdc-toolbar-fixed-adjust style property to provided value. |