# Materialize User Guide

Materialize is a modern, responsive front-end framework based on Google's **Material Design** language. It gives you a 12-column responsive grid, a large catalog of styled components (buttons, cards, modals, carousels, date/time pickers, and more), and a set of JavaScript plugins that bring those components to life — all from two files you drop into your page.

This guide shows you how to install Materialize, build responsive layouts, use every component, and initialize the interactive JavaScript pieces. Written from the framework's source code at version `1.0.0`.

> [!NOTE]
> Materialize is a **CSS/JavaScript framework**, not an application you run. You use it by linking its CSS and JS into your HTML pages and applying its classes and markup patterns to your own elements.

---

## 1. Quick Start

Get a working Materialize page in under a minute using the CDN.

1. Create an `index.html` file.
2. Paste the template below.
3. Open it in a browser.

```html
<!DOCTYPE html>
<html>
  <head>
    <!-- Import Google Material Icons font -->
    <link href="https://fonts.googleapis.com/icon?family=Material+Icons" rel="stylesheet">

    <!-- Import compiled and minified Materialize CSS -->
    <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/materialize/1.0.0/css/materialize.min.css">

    <!-- Tell the browser the site is mobile-optimized -->
    <meta name="viewport" content="width=device-width, initial-scale=1.0"/>
  </head>

  <body>
    <div class="container">
      <h1>Hello, Materialize</h1>
      <a class="btn waves-effect waves-light" href="#">Click me<i class="material-icons right">send</i></a>
    </div>

    <!-- Import compiled and minified Materialize JS at the end of body -->
    <script src="https://cdnjs.cloudflare.com/ajax/libs/materialize/1.0.0/js/materialize.min.js"></script>
  </body>
</html>
```

```text
A centered container with a styled "Hello, Materialize" heading and a red
raised button with a ripple (waves) effect and a paper-plane icon.
```

> [!TIP]
> Always place the `<script>` tag for `materialize.min.js` at the **end of `<body>`**, not in the `<head>`. This lets the page render before JavaScript loads, reducing perceived load time.

> [!IMPORTANT]
> The Material Icons font link is required if you use `<i class="material-icons">` icons (and many components use them). Without it, icon names render as plain text.

---

## 2. Installation

Materialize ships in two forms:

- **Standard** — pre-compiled, minified and unminified CSS and JS. No build tools needed. Use this if you are not familiar with Sass.
- **Sass (source)** — the raw `.scss` source files plus JS. Lets you choose which components to include and customize design variables. Requires a Sass compiler.

Choose the install method that fits your workflow.

=== "CDN"

    No download required — link directly from cdnjs.

    ```html
    <!-- Compiled and minified CSS -->
    <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/materialize/1.0.0/css/materialize.min.css">

    <!-- Compiled and minified JavaScript -->
    <script src="https://cdnjs.cloudflare.com/ajax/libs/materialize/1.0.0/js/materialize.min.js"></script>
    ```

    All available versions are listed at [cdnjs.com/libraries/materialize](https://cdnjs.com/libraries/materialize).

=== "npm"

    ```bash
    npm install materialize-css
    ```

    ```text
    + materialize-css@1.0.0
    ```

    The package's `main` entry is `dist/js/materialize.js` and its `style`
    entry is `dist/css/materialize.css`. The Sass entry point is
    `sass/materialize.scss`.

=== "Bower"

    ```bash
    bower install materialize
    ```

    > [!WARNING]
    > Bower is deprecated. Prefer npm or the CDN for new projects.

=== "Meteor"

    ```bash
    meteor add materialize:materialize
    ```

=== "Download"

    Download a release archive directly from GitHub and extract it into your
    project:

    - Standard build: `materialize-v1.0.0.zip`
    - Sass source build: `materialize-src-v1.0.0.zip`

    Get them from the [releases page](https://github.com/Dogfalo/materialize/releases/latest).

> [!NOTE]
> The npm package is named **`materialize-css`**, but the Bower and Meteor packages are named **`materialize`**. Use the correct name for your tool.

### Project structure (standard build)

After extracting a standard download, arrange your project like this:

```text
MyWebsite/
|--css/
|  |--materialize.css        (or materialize.min.css for production)
|
|--fonts/
|  |--roboto/                (the Roboto font family, included)
|
|--js/
|  |--materialize.js         (or materialize.min.js for production)
|
|--index.html
```

> [!TIP]
> Use the **minified** files (`materialize.min.css`, `materialize.min.js`) in production for faster load times, and the unminified files during development for easier debugging.

### HTML setup

Link the files in your page as shown in the [Quick Start](#1-quick-start): the Material Icons font and `materialize.min.css` go in the `<head>`, and `materialize.min.js` goes at the end of `<body>`.

### Supported browsers

Materialize is compatible with:

| Browser | Minimum version |
|---|---|
| Google Chrome | 35+ |
| Mozilla Firefox | 31+ |
| Safari | 9+ |
| Opera | (current) |
| Microsoft Edge | (current) |
| Internet Explorer | 11+ |

---

## 3. The Grid

Materialize uses a standard **12-column responsive grid**. Layouts are built from three pieces:

- `.container` — centers content and constrains its width.
- `.row` — a horizontal group of columns; clears floats.
- `.col` — a column; you give it width classes per screen size.

```html
<div class="container">
  <div class="row">
    <div class="col s12 m6 l4">Column A</div>
    <div class="col s12 m6 l4">Column B</div>
    <div class="col s12 m12 l4">Column C</div>
  </div>
</div>
```

### Breakpoints

Column width classes are prefixed by the screen size they apply to. A class applies at its breakpoint **and up** until a larger class overrides it.

| Prefix | Screen size | Activates at |
|---|---|---|
| `s` | Small (mobile) | 0px and up |
| `m` | Medium (tablet) | 601px and up |
| `l` | Large (desktop) | 993px and up |
| `xl` | Extra large | 1201px and up |

The number after the prefix is how many of the 12 columns to span. For example, `col s12 m6 l4`:

- On phones (`s`): full width (12 of 12).
- On tablets (`m`): half width (6 of 12).
- On desktops (`l`): one third (4 of 12).

> [!TIP]
> The 12 column widths add up across a row. Make sure each row's columns total 12 (per breakpoint) for a clean layout. Columns beyond 12 wrap to the next line.

### Offsets, push, and pull

Shift columns horizontally without adding empty columns.

| Class | Effect |
|---|---|
| `offset-s3`, `offset-m2`, `offset-l1`, `offset-xl1` | Add left margin equal to *n* columns |
| `push-s3`, `push-m2`, … | Move the column *right* by *n* columns |
| `pull-s3`, `pull-m2`, … | Move the column *left* by *n* columns |

```html
<div class="row">
  <div class="col s12 m8 offset-m2">Centered on tablet+ (2-col margin each side)</div>
</div>
```

`push`/`pull` are useful for reordering columns visually (e.g. showing a sidebar before content in source but after it on screen).

### The container

`.container` is responsive by design:

- Mobile: 90% width
- Medium and up: 85% width
- Large and up: 70% width
- Maximum width: 1280px

Wrap page content in a `.container` to keep line lengths comfortable. Full-bleed sections (like a parallax banner) can live outside a container.

---

## 4. Color & Icons

### Colors

Materialize ships the full Material Design color palette as helper classes. Apply a color name as a **background** class, and add a variant for shade:

```html
<span class="red">red background</span>
<span class="teal lighten-2">lighter teal background</span>
<span class="blue darken-3">darker blue background</span>
```

Add `-text` to color the **text** instead of the background:

```html
<span class="red-text">red text</span>
<span class="teal-text text-lighten-2">lighter teal text</span>
```

> [!NOTE]
> Variants follow the Material Design scale: `lighten-1` through `lighten-5`, `darken-1` through `darken-4`, and `accent-1` through `accent-4`. For text variants, prefix the shade with `text-` (e.g. `text-darken-2`).

### Icons

Materialize uses the **Material Icons** font. Add an icon with an `<i>` element whose text is the icon name:

```html
<i class="material-icons">cloud</i>
<i class="material-icons">favorite</i>
<i class="material-icons">delete</i>
```

Many components position icons with helper classes:

```html
<a class="btn">
  Upload<i class="material-icons right">file_upload</i>
</a>
```

| Class | Effect |
|---|---|
| `left` | Float the icon to the left of text |
| `right` | Float the icon to the right of text |
| `tiny`, `small`, `medium`, `large` | Scale the icon |

---

## 5. Static Components

These components are pure CSS — apply the classes and the markup pattern, no JavaScript required.

### Buttons

```html
<!-- Raised (default) -->
<a class="btn waves-effect waves-light">Button</a>

<!-- Floating action button -->
<a class="btn-floating waves-effect waves-light red">
  <i class="material-icons">add</i>
</a>

<!-- Flat (no background) -->
<a class="btn-flat waves-effect">Flat</a>

<!-- Large / small -->
<a class="btn-large">Large</a>
<a class="btn-small">Small</a>

<!-- Disabled -->
<a class="btn disabled">Disabled</a>
```

The `waves-effect waves-light` classes add the Material "ripple" animation on click. Use `waves-light` on dark buttons and `waves-effect` alone on light ones.

### Cards

```html
<div class="card">
  <div class="card-content">
    <span class="card-title">Card Title</span>
    <p>This is some card content.</p>
  </div>
  <div class="card-action">
    <a href="#">Action 1</a>
    <a href="#">Action 2</a>
  </div>
</div>
```

Cards support an image header (`.card-image`) and a reveal panel that slides up when the card is clicked:

```html
<div class="card">
  <div class="card-content">
    <span class="card-title activator">More<i class="material-icons right">more_vert</i></span>
  </div>
  <div class="card-reveal">
    <span class="card-title">More<i class="material-icons right">close</i></span>
    <p>Revealed content.</p>
  </div>
</div>
```

> [!NOTE]
> The card reveal panel is wired automatically by Materialize's JavaScript — it listens for clicks on `.card .activator` to open and `.card-reveal .card-title` to close. No manual initialization is needed.

### Badges

```html
<a href="#">Inbox<span class="badge">4</span></a>
<a href="#">Updates<span class="new badge">1</span></a>
<span class="badge" data-badge-caption="unread">12</span>
```

Add `new` for a colored badge; use `data-badge-caption` to append a word after the number.

### Navbar

```html
<nav>
  <div class="nav-wrapper">
    <a href="#" class="brand-logo">Logo</a>
    <ul class="right hide-on-med-and-down">
      <li><a href="#">Link 1</a></li>
      <li><a href="#">Link 2</a></li>
    </ul>
  </div>
</nav>
```

### Typography

| Class | Use |
|---|---|
| `.flow-text` | Responsive paragraph text that scales with viewport |
| `.light`, `.thin` | Font weights |
| `.truncate` | Truncate overflowing text with an ellipsis |
| `.left-align`, `.center-align`, `.right-align` | Text alignment |

Heading sizes are large by default (`h1` ≈ 4.2rem down to `h6` ≈ 1.15rem) to match Material Design.

### Collections (lists)

```html
<ul class="collection">
  <li class="collection-item">Item one</li>
  <li class="collection-item active">Item two (active)</li>
  <li class="collection-item">Item three</li>
</ul>
```

### Tables

```html
<table class="striped highlight responsive-table">
  <thead><tr><th>Name</th><th>Age</th></tr></thead>
  <tbody><tr><td>Ada</td><td>36</td></tr></tbody>
</table>
```

| Class | Effect |
|---|---|
| `striped` | Alternating row backgrounds |
| `highlight` | Highlight a row on hover |
| `centered` | Center all cells |
| `responsive-table` | Scroll horizontally on small screens |

### Shadows & helpers

| Class | Effect |
|---|---|
| `z-depth-1` … `z-depth-5` | Material elevation shadow |
| `hoverable` | Add elevation on hover |
| `hide` | Hide always |
| `hide-on-small-only`, `hide-on-med-only`, `hide-on-med-and-down`, `hide-on-med-and-up`, `hide-on-large-only` | Responsive visibility |
| `center-on-small-only` | Center text on mobile |
| `valign-wrapper` | Vertically center children |

### Preloaders

```html
<!-- Circular spinner -->
<div class="preloader-wrapper active">
  <div class="spinner-layer spinner-blue-only">
    <div class="circle-clipper left"><div class="circle"></div></div>
    <div class="gap-patch"><div class="circle"></div></div>
    <div class="circle-clipper right"><div class="circle"></div></div>
  </div>
</div>

<!-- Linear progress bar -->
<div class="progress"><div class="indeterminate"></div></div>
```

### Pulse & waves

- `pulse` — add to an element (often a `btn-floating`) for a pulsing attention animation.
- `waves-effect` (+ `waves-light`/`waves-red`/etc.) — the Material ripple on click. Works on any clickable element.

---

## 6. Initializing JavaScript Components

The interactive components (modals, dropdowns, carousels, pickers, and more) are powered by JavaScript and must be **initialized** before they work. Materialize gives you three ways to do it.

### Option 1 — Auto-initialization (easiest)

Call `M.AutoInit()` once after the DOM is ready. It scans the page and initializes every recognized component using its default options.

```html
<script>
  document.addEventListener('DOMContentLoaded', function() {
    M.AutoInit();
  });
</script>
```

Auto-init finds components by CSS selector. To exclude a specific element from auto-init, add the `no-autoinit` class to it.

| Component | Selector auto-init looks for |
|---|---|
| Autocomplete | `.autocomplete` |
| Carousel | `.carousel` |
| Chips | `.chips` |
| Collapsible | `.collapsible` |
| Datepicker | `.datepicker` |
| Dropdown | `.dropdown-trigger` |
| Materialbox | `.materialboxed` |
| Modal | `.modal` |
| Parallax | `.parallax` |
| Pushpin | `.pushpin` |
| ScrollSpy | `.scrollspy` |
| Select | `select` |
| Sidenav | `.sidenav` |
| Tabs | `.tabs` |
| TapTarget | `.tap-target` |
| Timepicker | `.timepicker` |
| Tooltip | `.tooltipped` |
| Floating Action Button | `.fixed-action-btn` |

> [!TIP]
> Auto-init uses each component's default options. When you need custom options (a callback, a different duration, etc.), initialize that component manually instead.

### Option 2 — Vanilla JavaScript

Every component is exposed on the global `M` object. Use `init()` to initialize and `getInstance()` to retrieve the instance and call methods.

```html
<script>
  document.addEventListener('DOMContentLoaded', function() {
    // Initialize all modals with custom options
    var elems = document.querySelectorAll('.modal');
    var instances = M.Modal.init(elems, { opacity: 0.4, inDuration: 300 });

    // Initialize one element and keep a reference
    var el = document.querySelector('#my-modal');
    var instance = M.Modal.init(el, {});
    instance.open();
  });
</script>
```

To get an existing instance later:

```javascript
var elem = document.querySelector('#my-modal');
var instance = M.Modal.getInstance(elem);
instance.close();
```

### Option 3 — jQuery (optional)

If jQuery is loaded **before** Materialize, a jQuery plugin is registered for each component. Initialize with options, then call methods by name.

```javascript
// Initialize
$('.modal').modal({ opacity: 0.4 });

// Call a method
$('#my-modal').modal('open');
$('#my-modal').modal('close');

// Getter methods (prefix get)
var instance = $('#my-modal').modal('getInstance');
```

> [!NOTE]
> jQuery is **optional**. Materialize ships its own lightweight DOM library (`cash`) internally, so the vanilla `M.*` API works with no extra dependencies. The jQuery wrapper is only registered when jQuery is detected at load time.

> [!CAUTION]
> Calling a jQuery method that doesn't exist throws `Method <name> does not exist on jQuery.<plugin>`. Check the component's method list in this guide before calling.

---

## 7. Interactive Components Reference

Each component below lists its trigger markup, key options (passed to `init`), and public methods. Options use their **exact source defaults**.

### Modal

A dialog overlay.

```html
<a class="waves-effect waves-light btn modal-trigger" href="#modal1">Open Modal</a>

<div id="modal1" class="modal">
  <div class="modal-content"><h4>Title</h4><p>Modal body.</p></div>
  <div class="modal-footer">
    <a href="#!" class="modal-close waves-effect btn-flat">Close</a>
  </div>
</div>
```

A link with `class="modal-trigger"` and `href="#modal1"` opens the matching modal automatically. Add `modal-close` to any element inside to close it.

| Option | Default | Description |
|---|---|---|
| `opacity` | `0.5` | Opacity of the overlay |
| `inDuration` | `250` | Enter transition (ms) |
| `outDuration` | `250` | Exit transition (ms) |
| `dismissible` | `true` | Allow closing by clicking the overlay / pressing Esc |
| `startingTop` | `'4%'` | Starting top offset of the modal |
| `endingTop` | `'10%'` | Ending top offset |
| `preventScrolling` | `true` | Prevent page scroll while open |
| `onOpenStart` / `onOpenEnd` / `onCloseStart` / `onCloseEnd` | `null` | Lifecycle callbacks |

**Methods:** `open()`, `close()`, `destroy()`.

### Dropdown

```html
<a class="dropdown-trigger btn" data-target="dropdown1">Menu</a>
<ul id="dropdown1" class="dropdown-content">
  <li><a href="#!">One</a></li>
  <li><a href="#!">Two</a></li>
</ul>
```

| Option | Default | Description |
|---|---|---|
| `alignment` | `'left'` | `left` or `right` edge alignment |
| `autoFocus` | `true` | Focus the dropdown when opened |
| `constrainWidth` | `true` | Match dropdown width to trigger |
| `coverTrigger` | `true` | Position the dropdown over the trigger |
| `closeOnClick` | `true` | Close when an item is clicked |
| `hover` | `false` | Open on hover instead of click |
| `inDuration` / `outDuration` | `150` / `250` | Transition durations (ms) |
| `onItemClick` | `null` | Callback when an item is clicked |
| `onOpenStart` / `onOpenEnd` / `onCloseStart` / `onCloseEnd` | `null` | Lifecycle callbacks |

**Methods:** `open()`, `close()`, `recalculateDimensions()`, `destroy()`.

### Sidenav (side navigation drawer)

```html
<a href="#" data-target="slide-out" class="sidenav-trigger"><i class="material-icons">menu</i></a>
<ul id="slide-out" class="sidenav">
  <li><a href="#!">Home</a></li>
  <li><a href="#!">Profile</a></li>
</ul>
```

| Option | Default | Description |
|---|---|---|
| `edge` | `'left'` | Side the drawer slides from (`left`/`right`) |
| `draggable` | `true` | Allow opening by dragging from the edge |
| `inDuration` / `outDuration` | `250` / `200` | Transition durations (ms) |
| `preventScrolling` | `true` | Prevent body scroll while open |
| `onOpenStart` / `onOpenEnd` / `onCloseStart` / `onCloseEnd` | `null` | Lifecycle callbacks |

**Methods:** `open()`, `close()`, `destroy()`.

### Tabs

```html
<ul class="tabs">
  <li class="tab"><a class="active" href="#tab1">Tab 1</a></li>
  <li class="tab"><a href="#tab2">Tab 2</a></li>
</ul>
<div id="tab1">Content 1</div>
<div id="tab2">Content 2</div>
```

| Option | Default | Description |
|---|---|---|
| `duration` | `300` | Transition duration (ms) |
| `swipeable` | `false` | Enable swipe gestures between tabs |
| `responsiveThreshold` | `Infinity` | Width below which tabs become swipeable |
| `onShow` | `null` | Callback when a tab is shown |

**Methods:** `select(tabId)`, `updateTabIndicator()`, `destroy()`.

### Collapsible / Accordion

```html
<ul class="collapsible">
  <li>
    <div class="collapsible-header"><i class="material-icons">filter_drama</i>First</div>
    <div class="collapsible-body"><span>Body</span></div>
  </li>
</ul>
```

| Option | Default | Description |
|---|---|---|
| `accordion` | `true` | Only one section open at a time (set `false` for expandable) |
| `inDuration` / `outDuration` | `300` / `300` | Transition durations (ms) |
| `onOpenStart` / `onOpenEnd` / `onCloseStart` / `onCloseEnd` | `undefined` | Lifecycle callbacks |

**Methods:** `open(index)`, `close(index)`, `destroy()`.

### Carousel

```html
<div class="carousel">
  <a class="carousel-item" href="#one!"><img src="img1.jpg"></a>
  <a class="carousel-item" href="#two!"><img src="img2.jpg"></a>
</div>
```

| Option | Default | Description |
|---|---|---|
| `duration` | `200` | Transition duration (ms) |
| `dist` | `-100` | Zoom-out distance of non-center items |
| `shift` | `0` | Spacing for the center image |
| `padding` | `0` | Padding between non-center items |
| `numVisible` | `5` | Number of visible items |
| `fullWidth` | `false` | Full-width slider mode (use with `indicators`) |
| `indicators` | `false` | Show indicator dots |
| `noWrap` | `false` | Don't cycle past the last item |
| `onCycleTo` | `null` | Callback when a new slide is shown |

**Methods:** `next(n)`, `prev(n)`, `set(n, callback)`, `destroy()`.

### Slider (image slideshow)

```html
<div class="slider">
  <ul class="slides">
    <li><img src="img1.jpg"><div class="caption center-align"><h3>Caption</h3></div></li>
    <li><img src="img2.jpg"></li>
  </ul>
</div>
```

| Option | Default | Description |
|---|---|---|
| `indicators` | `true` | Show indicator dots |
| `height` | `400` | Slider height (px) |
| `duration` | `500` | Transition duration (ms) |
| `interval` | `6000` | Time between auto-advances (ms) |

**Methods:** `start()`, `pause()`, `next()`, `prev()`, `set(index)`, `destroy()`.

### Materialbox (lightbox)

Add `materialboxed` to an image to make it zoom to the center of the screen on click.

```html
<img class="materialboxed" width="650" src="image.jpg">
```

| Option | Default | Description |
|---|---|---|
| `inDuration` | `275` | Enter transition (ms) |
| `outDuration` | `200` | Exit transition (ms) |
| `onOpenStart` / `onOpenEnd` / `onCloseStart` / `onCloseEnd` | `null` | Lifecycle callbacks |

**Methods:** `open()`, `close()`, `destroy()`.

### Tooltip

```html
<a class="btn tooltipped" data-position="bottom" data-tooltip="I am a tooltip">Hover me</a>
```

| Option | Default | Description |
|---|---|---|
| `position` | `'bottom'` | `top` / `right` / `bottom` / `left` |
| `enterDelay` | `0` | Delay before showing (ms) |
| `exitDelay` | `200` | Delay before hiding (ms) |
| `html` | `null` | Tooltip content (overrides `data-tooltip`) |
| `margin` | `5` | Gap from the element (px) |
| `inDuration` / `outDuration` | `250` / `200` | Transition durations (ms) |
| `transitionMovement` | `10` | Distance the tooltip travels in (px) |

**Methods:** `open()`, `close()`, `destroy()`.

### Floating Action Button (FAB)

```html
<div class="fixed-action-btn">
  <a class="btn-floating btn-large red"><i class="large material-icons">mode_edit</i></a>
  <ul>
    <li><a class="btn-floating red"><i class="material-icons">insert_chart</i></a></li>
    <li><a class="btn-floating yellow darken-1"><i class="material-icons">format_quote</i></a></li>
  </ul>
</div>
```

| Option | Default | Description |
|---|---|---|
| `direction` | `'top'` | Menu open direction: `top`/`right`/`bottom`/`left` |
| `hoverEnabled` | `true` | Open on hover (vs click) |
| `toolbarEnabled` | `false` | Use the toolbar transition |

**Methods:** `open()`, `close()`, `destroy()`.

### Autocomplete

```html
<div class="input-field">
  <input type="text" id="autocomplete-input" class="autocomplete">
  <label for="autocomplete-input">Autocomplete</label>
</div>
```

```javascript
M.Autocomplete.init(document.querySelector('.autocomplete'), {
  data: { 'Apple': null, 'Microsoft': null, 'Google': 'https://.../logo.png' }
});
```

| Option | Default | Description |
|---|---|---|
| `data` | `{}` | Map of suggestion text → image URL (or `null`) |
| `limit` | `Infinity` | Maximum suggestions shown |
| `minLength` | `1` | Characters typed before suggesting |
| `onAutocomplete` | `null` | Callback when a suggestion is selected |
| `sortFunction` | (alphabetical-ish) | Custom sort comparator |

**Methods:** `open()`, `close()`, `selectOption(el)`, `updateData(data)`, `destroy()`.

### Chips

```html
<div class="chips"></div>
<div class="chips chips-placeholder"></div>
```

| Option | Default | Description |
|---|---|---|
| `data` | `[]` | Initial chips (`{ tag, image }`) |
| `placeholder` | `''` | Placeholder before any chips |
| `secondaryPlaceholder` | `''` | Placeholder after first chip |
| `autocompleteOptions` | `{}` | Options object passed to an embedded autocomplete |
| `limit` | `Infinity` | Maximum number of chips |
| `onChipAdd` / `onChipSelect` / `onChipDelete` | `null` | Callbacks |

**Methods:** `addChip(chip)`, `deleteChip(chipIndex)`, `selectChip(chipIndex)`, `getData()`, `destroy()`.

### Datepicker

```html
<input type="text" class="datepicker">
```

| Option | Default | Description |
|---|---|---|
| `format` | `'mmm dd, yyyy'` | Output date format |
| `autoClose` | `false` | Close when a date is selected |
| `defaultDate` | `null` | Date shown when first opened |
| `setDefaultDate` | `false` | Make `defaultDate` the selected value |
| `minDate` / `maxDate` | `null` | Selectable date range |
| `yearRange` | `10` | Years shown around the current year |
| `firstDay` | `0` | First day of week (0 = Sunday) |
| `disableWeekends` | `false` | Disable Saturdays and Sundays |
| `disableDayFn` | `null` | Function returning `true` to disable a day |
| `showClearBtn` | `false` | Show a Clear button |
| `i18n` | (English) | Labels and month/weekday names |

**Methods:** `setDate(date)`, `gotoDate(date)`, `nextMonth()`, `prevMonth()`, `toString(format)`, `destroy()`.

> [!WARNING]
> A community-reported bug (issue #6011) notes the Datepicker can select the wrong date if `setDate` is called before initialization completes. Call `setDate` after the instance is fully initialized.

### Timepicker

```html
<input type="text" class="timepicker">
```

| Option | Default | Description |
|---|---|---|
| `twelveHour` | `true` | 12-hour AM/PM clock (set `false` for 24-hour) |
| `defaultTime` | `'now'` | Initial time (`'now'` or e.g. `'13:14'`) |
| `autoClose` | `false` | Close when a minute is selected |
| `showClearBtn` | `false` | Show a Clear button |
| `vibrate` | `true` | Vibrate the device while dragging the hand |
| `duration` | `350` | Animation duration (ms) |
| `i18n` | `{ cancel, clear, done }` | Button labels |

**Methods:** `open()`, `close()`, `showView(view)`, `clear()`, `destroy()`.

### ScrollSpy

Highlights navigation links as you scroll past the sections they point to.

```html
<div class="section scrollspy" id="section1">...</div>
```

| Option | Default | Description |
|---|---|---|
| `throttle` | `100` | Scroll handler throttle (ms) |
| `scrollOffset` | `200` | Offset from top that counts as "in view" |
| `activeClass` | `'active'` | Class added to the active link |
| `getActiveElement` | (matches `a[href="#id"]`) | Function returning the link selector for a section id |

### Pushpin

Pins an element to the viewport while scrolling within a range.

| Option | Default | Description |
|---|---|---|
| `top` | `0` | Scroll position where pinning starts |
| `bottom` | `Infinity` | Scroll position where pinning ends |
| `offset` | `0` | Offset from top once pinned (px) |
| `onPositionChange` | `null` | Callback when pin state changes |

### Parallax

```html
<div class="parallax-container">
  <div class="parallax"><img src="background.jpg"></div>
</div>
```

| Option | Default | Description |
|---|---|---|
| `responsiveThreshold` | `0` | Width below which the parallax effect is disabled |

### Tap Target (feature discovery)

```html
<div class="tap-target" data-target="menu-button">
  <div class="tap-target-content"><h5>Title</h5><p>Tip text.</p></div>
</div>
```

| Option | Default | Description |
|---|---|---|
| `onOpen` | `undefined` | Callback when opened |
| `onClose` | `undefined` | Callback when closed |

**Methods:** `open()`, `close()`, `destroy()`.

---

## 8. Forms

Materialize restyles native form controls. Wrap text inputs in `.input-field` to get the floating-label effect.

### Text inputs

```html
<div class="input-field">
  <input id="email" type="email" class="validate">
  <label for="email">Email</label>
  <span class="helper-text" data-error="Invalid email" data-success="Looks good">Helper text</span>
</div>
```

- Add `validate` to enable validation styling (red on invalid, green on valid).
- Add the `active` class to a label, or use `M.updateTextFields()`, when an input is pre-filled so the label floats correctly.

```html
<textarea id="bio" class="materialize-textarea"></textarea>
```

`materialize-textarea` makes a textarea auto-resize as you type.

### Select

```html
<div class="input-field">
  <select>
    <option value="" disabled selected>Choose your option</option>
    <option value="1">Option 1</option>
    <option value="2">Option 2</option>
  </select>
  <label>Materialize Select</label>
</div>
```

| Option | Default | Description |
|---|---|---|
| `classes` | `''` | Extra classes for the generated dropdown |
| `dropdownOptions` | `{}` | Options forwarded to the underlying Dropdown |

To keep a browser's native select, add `class="browser-default"` — Materialize will skip it.

### Checkboxes, radios, switches

```html
<!-- Checkbox -->
<label><input type="checkbox" /><span>Remember me</span></label>

<!-- Radio -->
<label><input name="group1" type="radio" checked /><span>Option A</span></label>

<!-- Switch -->
<div class="switch">
  <label>Off<input type="checkbox"><span class="lever"></span>On</label>
</div>
```

### Range slider

```html
<form action="#">
  <p class="range-field">
    <input type="range" id="amount" min="0" max="100" />
  </p>
</form>
```

### File input

```html
<div class="file-field input-field">
  <div class="btn"><span>File</span><input type="file"></div>
  <div class="file-path-wrapper">
    <input class="file-path validate" type="text">
  </div>
</div>
```

### Character counter

Add `data-length` to any text input or textarea and it will display a live character counter.

```html
<input type="text" data-length="10">
```

### Form helper functions

| Function | Use |
|---|---|
| `M.updateTextFields()` | Re-position labels after programmatically setting input values |
| `M.textareaAutoResize($textarea)` | Manually trigger textarea auto-resize |
| `M.validate_field($input)` | Manually run validation styling on a field |

---

## 9. Toasts

Toasts are brief, non-blocking notifications. Trigger them from JavaScript:

```javascript
M.toast({ html: 'Saved!' });

M.toast({
  html: 'Item deleted <button class="btn-flat toast-action">Undo</button>',
  displayLength: 6000,
  classes: 'rounded'
});
```

| Option | Default | Description |
|---|---|---|
| `html` | `''` | Toast content (HTML allowed) |
| `displayLength` | `4000` | Time on screen before auto-dismiss (ms) |
| `inDuration` | `300` | Enter transition (ms) |
| `outDuration` | `375` | Exit transition (ms) |
| `classes` | `''` | Extra CSS classes |
| `completeCallback` | `null` | Called after the toast dismisses |
| `activationPercent` | `0.8` | Swipe-distance fraction needed to dismiss |

To dismiss programmatically, keep the returned instance and call `dismiss()`, or call `M.Toast.dismissAll()` to clear all toasts.

```javascript
var toast = M.toast({ html: 'Working…' });
toast.dismiss();
```

---

## 10. Starter Templates

Materialize ships ready-to-use page templates you can download and adapt:

| Template | Description |
|---|---|
| **Starter Template** | Simplest page: header, call-to-action, icon features |
| **Parallax Template** | Page with parallax background sections |
| **Masonry Template** | Pinterest-style masonry grid layout (uses Masonry.js) |

Each template is a self-contained folder with `index.html`, `preview.html`, a `css/style.css`, and a `js/init.js` that initializes the components used. For example, the starter template's init is simply:

```javascript
(function($){
  $(function(){
    $('.sidenav').sidenav();
  }); // end of document ready
})(jQuery);
```

---

## 11. Troubleshooting

### Components do nothing when clicked

**Cause:** The JavaScript component was never initialized.
**Solution:** Call `M.AutoInit()` (or the specific `M.<Component>.init(...)`) inside a `DOMContentLoaded` handler. See [Section 6](#6-initializing-javascript-components).
**Prevention:** Always initialize after the DOM is ready, and load `materialize.min.js` before your init script.

### Icons show as text instead of glyphs

**Cause:** The Material Icons font is not linked.
**Solution:** Add `<link href="https://fonts.googleapis.com/icon?family=Material+Icons" rel="stylesheet">` to your `<head>`.
**Prevention:** Include the icon font link in your base template.

### Floating labels overlap pre-filled input text

**Cause:** Labels don't know an input already has a value.
**Solution:** Add the `active` class to the label, or call `M.updateTextFields()` after setting values.

### Error: `Method <name> does not exist on jQuery.<plugin>`

**Cause:** You called a jQuery method name the component doesn't define.
**Solution:** Use only the documented methods for that component (see [Section 7](#7-interactive-components-reference)).
**Prevention:** Prefer the vanilla `M.<Component>.getInstance(el)` API and call methods on the instance.

### Select dropdown behaves unexpectedly

**Cause:** Several community issues (#6647, #6698, #1861) report edge cases with the custom Select, especially on iOS and with frameworks like AngularJS (#4529).
**Solution:** For maximum reliability, fall back to the native control with `class="browser-default"` on the `<select>`.

### Date picker selects the wrong date

**Cause:** `setDate` was called before initialization completed (issue #6011).
**Solution:** Call `setDate` only after `M.Datepicker.init(...)` has returned and the instance exists.

### Can't scroll after closing a modal

**Cause:** A reported edge case (issue #6130) where scroll lock isn't released.
**Solution:** Ensure each modal is opened/closed through its instance methods so cleanup runs; avoid removing modal DOM while it is open.

### Error: `<element> is not an HTML Element`

**Cause:** A component was initialized with something other than a DOM element (logged via `console.error`).
**Solution:** Pass a real element, NodeList, or jQuery/cash object to `init()`.

---

## 12. FAQ

**Q: Do I need jQuery to use Materialize?**
No. Materialize bundles its own lightweight DOM library (`cash`) and exposes a vanilla `M.*` API. jQuery support is enabled automatically only if jQuery is loaded before Materialize.

**Q: How do I customize the theme colors?**
The standard build can't be re-themed, but the color helper classes cover the full Material palette. For deep customization (changing the primary/secondary color globally), download the **Sass** version and override the design variables — see the Admin Guide.

**Q: What's the difference between the standard and Sass downloads?**
The standard download gives you pre-compiled CSS/JS with no setup. The Sass download gives you the `.scss` source so you can include only the components you need and customize variables, but requires a Sass compiler.

**Q: How many grid columns are there?**
Twelve. Use `s`/`m`/`l`/`xl` prefixes to set column spans per breakpoint.

**Q: How do I make an element initialize automatically but with custom options?**
You can't — `M.AutoInit()` always uses defaults. Add `no-autoinit` to that element and initialize it manually with your options.

**Q: How do I show a quick notification?**
Call `M.toast({ html: 'Your message' })`.

**Q: Which icon set does Materialize use?**
Google's Material Icons font. Reference an icon by name inside `<i class="material-icons">name</i>`.

**Q: Can I use only one or two components instead of the whole framework?**
Not from the standard build (it's one bundled CSS and one bundled JS file). With the Sass source you can comment out unused `@import`s in `sass/materialize.scss` to shrink the CSS. This is a long-requested feature (issue #6422).

**Q: How do I run the documentation site locally?**
Clone the repo, run `npm install`, then `grunt monitor`, and open `http://localhost:8000`. See the Admin Guide for the full build workflow.

**Q: Is Materialize still maintained?**
This repository (`Dogfalo/materialize`) is no longer actively maintained (issues #6615, #6691). It remains usable as-is at v1.0.0, but evaluate the maintenance status before adopting it for new long-lived projects.

---

_Generated June 2026 from Dogfalo/materialize at 824e782. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._