{"id":13701109,"url":"https://github.com/leifoolsen/mdl-ext","last_synced_at":"2025-04-26T17:31:22.987Z","repository":{"id":57293635,"uuid":"53355525","full_name":"leifoolsen/mdl-ext","owner":"leifoolsen","description":"Material Design Lite Ext: Components built with Google Material Design Lite framework. http://leifoolsen.github.io/mdl-ext/","archived":false,"fork":false,"pushed_at":"2017-03-13T07:23:23.000Z","size":31288,"stargazers_count":112,"open_issues_count":18,"forks_count":29,"subscribers_count":12,"default_branch":"master","last_synced_at":"2025-04-21T01:06:34.387Z","etag":null,"topics":["es2015","es6","javascript","material-design","material-design-lite","sass"],"latest_commit_sha":null,"homepage":"","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/leifoolsen.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-03-07T20:10:28.000Z","updated_at":"2023-10-24T10:55:40.000Z","dependencies_parsed_at":"2022-09-05T17:00:24.512Z","dependency_job_id":null,"html_url":"https://github.com/leifoolsen/mdl-ext","commit_stats":null,"previous_names":[],"tags_count":121,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leifoolsen%2Fmdl-ext","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leifoolsen%2Fmdl-ext/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leifoolsen%2Fmdl-ext/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leifoolsen%2Fmdl-ext/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/leifoolsen","download_url":"https://codeload.github.com/leifoolsen/mdl-ext/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251025764,"owners_count":21524860,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["es2015","es6","javascript","material-design","material-design-lite","sass"],"created_at":"2024-08-02T20:01:18.126Z","updated_at":"2025-04-26T17:31:19.486Z","avatar_url":"https://github.com/leifoolsen.png","language":"HTML","funding_links":[],"categories":["HTML"],"sub_categories":[],"readme":"# mdl-ext\n\n[![travis build](https://img.shields.io/travis/leifoolsen/mdl-ext.svg?style=flat-square)](https://travis-ci.org/leifoolsen/mdl-ext)\n[![codecov coverage](https://img.shields.io/codecov/c/github/leifoolsen/mdl-ext.svg?style=flat-square)](https://codecov.io/github/leifoolsen/mdl-ext)\n[![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg?style=flat-square)](https://github.com/semantic-release/semantic-release)\n[![Commitizen friendly](https://img.shields.io/badge/commitizen-friendly-brightgreen.svg?style=flat-square)](http://commitizen.github.io/cz-cli/)\n[![version](https://img.shields.io/npm/v/mdl-ext.svg?style=flat-square)](http://npm.im/mdl-ext)\n\n\nMaterial Design Lite Ext (MDLEXT).\nComponents built with the [Google Material Design Lite](https://github.com/google/material-design-lite) framework. MDLEXT provides the following components.\n\n* **Accordion**\u003cbr/\u003eA WAI-ARIA friendly accordion component with vertcial or horizontal layout.\u003cbr/\u003e**Note:** The accordion has been refactored and is not compatible with accordion prior to version 0.9.13\n* **Bordered fields**\u003cbr/\u003eThe Material Design Lite Ext (MDLEXT) bordered fields component demonstrates how you can create your own theme of MDL text fields.\n* **Carousel**\u003cbr/\u003eA responsive image carousel.\n* **Collapsible**\u003cbr/\u003eAccessible collapsible content regions.\n* **Color themes**\u003cbr/\u003eMaterial design color themes.\n* **Formatfield**\u003cbr/\u003eLanguage sensitive numberformatting.\n* **Grid**\u003cbr/\u003eA responsive grid based on element queries in favour of media queries.\n* **Lightboard**\u003cbr/\u003eA lightboard is a translucent surface illuminated from behind, used for situations where a shape laid upon the surface needs to be seen with high contrast. In the \"old days\" of photography photograpers used a lightboard to get a quick view of, sorting and organizing their slides.\n* **Lightbox**\u003cbr/\u003eA lightbox displays an image filling the screen, and dimming out the rest of the web page. It acts as a modal dialog using the `\u003cdialog\u003e` element as a container for the lightbox.\n* **Menu Button**\u003cbr/\u003eA WAI-ARIA friendly menu button.\n* **Selectfield**\u003cbr/\u003eThe Material Design Lite Ext (MDLEXT) select field component is an enhanced version of the standard HTML `\u003cselect\u003e` element.\n* **Sticky Header**\u003cbr/\u003eA sticky header makes site navigation easily accessible anywhere on the page and saves content space at the same.\n\n#### Live demo\nA Live demo of MDLEXT is available [here](http://leifoolsen.github.io/mdl-ext/index.html)\n\u003eWorks with modern browsers.\n\u003eTested on Edgde, IE11. Firefox: OSX, Ubuntu. Opera: OSX. Safari: OSX, IOS. Chrome: Win, Ubuntu, OSX, IOS, Android. \n\n## Introduction\nThe MDLEXT component library is built with responsiveness in mind. The pre built CSS provided in the lib directory therefore comes\nin two versions; one based on media queries and one based on **element queries**, using [eq.js](https://github.com/Snugug/eq.js).\nIf you build the CSS from SASS, just import the correct sass file, `mdl-ext.scss` or `mdl-ext-eqjs.scss`.\n\n### Responsive breakpoints\nA common metod in responsive design is to use media queries to apply styles based on device\ncharacteristics. The problem with media queries is that they relates to the viewport - so every time you\nwrite a media query for `max-width` or `min-width`, you’re connecting the appearance of your module to the\nwidth of the entire canvas, not the part of the canvas the component occupies.\n\n#### Media queries are a hack\nSome developers claim that [media queries are a hack](http://ianstormtaylor.com/media-queries-are-a-hack/),\nand I totally agree! Imagine a design with a sidebar and a content area. In a responsive,\nfluent design both the sidebar and the content has \"unknown\" widths. Trying to add e.g. a responsive grid into the content\narea which relies on media queries, where you have no knowledge of how much space your content occupies, is\nin my opinion almost an impossible task.\n\n#### Element queries to the rescue\nAn element query is similar to a media query in that, if a condition is met, some CSS will be applied.\nElement query conditions (such as `min-width`, `max-width`, `min-height` and `max-height`) are based on elements,\ninstead of the browser viewport. Unfortunately, CSS doesn’t yet support element queries, but there are a\ncouple of JavaScript-based polyfrills involving various syntaxes. **They are not standard - but that\nshould not stop us from using them.** Element-first design is the spirit of the Atomic design principle, but\nlooks very different in practice than how most people implement Atomic design using their mobile-first mindset.\nInstead of writing styles on advance for every conceivable situation a widget may find itself in, we are able\nto allow individual parts of the layout to adapt responsively when those elements require it.\n\nSome of the polyfrills available are:\n* [eq.js](https://github.com/Snugug/eq.js)\n* [EQCSS](https://github.com/eqcss/eqcss)\n* [CSS Element Queries](https://github.com/marcj/css-element-queries)\n* [BoomQueries](https://github.com/BoomTownROI/boomqueries)\n\nThese are all good libraries, and they serve the purpose. After some evaluation I decided to go for\n[**eq.js**](https://github.com/Snugug/eq.js). It is a small library with support for width based breakpoints.\nIt works without requiring a server to run (no Ajax stuff). It does not break the existing CSS standard.\nI can use SASS for styling, and it works well in a Webpack workflow.\n\n## Install\nIf you haven't done so already, install [Material Design Lite](https://github.com/google/material-design-lite).\n\n```sh\n$ npm install --save material-design-lite\n```\n\nInstall **mdl-ext**\n```sh\n$ npm install --save mdl-ext\n```\n\nInstall **eq.js** if you choose to use the element query CSS/SASS version.\n```sh\n$ npm install --save eq.js\n```\n\n## Getting started\n\n### Use it in your (static) page\n```html\n\u003c!DOCTYPE html\u003e\n\u003chtml\u003e\n\u003chead\u003e\n  \u003ctitle\u003eMaterial Design Lite Extensions\u003c/title\u003e\n  \u003clink rel=\"stylesheet\" href=\"https://fonts.googleapis.com/css?family=Roboto:regular,bold,italic,thin,light,bolditalic,black,medium\u0026amp;lang=en\"\u003e\n  \u003clink rel=\"stylesheet\" href=\"https://fonts.googleapis.com/icon?family=Material+Icons\"\u003e\n  \u003clink rel=\"stylesheet\" href=\"node_modules/material-design-lite/material.css\" /\u003e\n  \u003clink rel=\"stylesheet\" href=\"node_modules/mdl-ext/lib/mdl-ext.min.css\" /\u003e\n\u003c/head\u003e\n\u003cbody\u003e\n\u003cdiv class=\"mdl-layout mdl-js-layout mdl-layout--fixed-drawer\"\u003e\n  \u003cmain class=\"mdl-layout__content\"\u003e\n  \u003c/main\u003e\n\u003c/div\u003e\n\u003cscript src=\"https://cdn.polyfill.io/v2/polyfill.min.js\"\u003e\u003c/script\u003e\n\u003cscript type=\"text/javascript\" src=\"node_modules/material-design-lite/material.min.js\" charset=\"utf-8\"\u003e\u003c/script\u003e\n\u003cscript type=\"text/javascript\" src=\"node_modules/mdl-ext/lib/mdl-ext.min.js\" charset=\"utf-8\"\u003e\u003c/script\u003e\n\u003c/body\u003e\n\u003c/html\u003e\n```\n\n\u003e**Note:** You'll probably need several polyfills. If you don't want to waist time writing your own polyfills, the [polyfill.io](https://polyfill.io/v2/docs/) hosted service is a good choice. \n```html\n\u003cscript src=\"https://cdn.polyfill.io/v2/polyfill.min.js\"\u003e\u003c/script\u003e\n```\n\n### Use it with element queries in your (static) page\n```html\n\u003c!DOCTYPE html\u003e\n\u003chtml\u003e\n\u003chead\u003e\n  \u003ctitle\u003eMaterial Design Lite Extensions\u003c/title\u003e\n  \u003clink rel=\"stylesheet\" href=\"https://fonts.googleapis.com/css?family=Roboto:regular,bold,italic,thin,light,bolditalic,black,medium\u0026amp;lang=en\"\u003e\n  \u003clink rel=\"stylesheet\" href=\"https://fonts.googleapis.com/icon?family=Material+Icons\"\u003e\n  \u003clink rel=\"stylesheet\" href=\"node_modules/material-design-lite/material.css\" /\u003e\n  \u003clink rel=\"stylesheet\" href=\"node_modules/mdl-ext/lib/mdl-ext-eqjs.min.css\" /\u003e\n\u003c/head\u003e\n\u003cbody\u003e\n\u003cdiv class=\"mdl-layout mdl-js-layout mdl-layout--fixed-drawer\"\u003e\n  \u003cmain class=\"mdl-layout__content\"\u003e\n  \u003c/main\u003e\n\u003c/div\u003e\n\u003cscript src=\"https://cdn.polyfill.io/v2/polyfill.min.js\"\u003e\u003c/script\u003e\n\u003cscript type=\"text/javascript\" src=\"node_modules/material-design-lite/material.min.js\" charset=\"utf-8\"\u003e\u003c/script\u003e\n\u003cscript type=\"text/javascript\" src=\"node_modules/mdl-ext/lib/mdl-ext.min.js\" charset=\"utf-8\"\u003e\u003c/script\u003e\n\u003cscript type=\"text/javascript\" src=\"node_modules/eq.js/dist/eq.min.js\" charset=\"utf-8\"\u003e\u003c/script\u003e\n\u003c/body\u003e\n\u003c/html\u003e\n```\n\n\u003e**Note:** Always import `mdl-ext` css **after** `material` css. Adjust path to `node_modules` (libraries) according to where your HTML file is located.\n\n### Use it in your (webpack) build\n\n**Import SASS files into your main SCSS file, e.g. `./src/styles.scss`**\n\n```scss\n@charset \"UTF-8\";\n\n// 1.  Configuration and helpers\n\n// MDL image path\n$image_path: '~material-design-lite/src/images';\n\n// 2. Vendors\n\n// Import MDL\n@import '~material-design-icons/iconfont/material-icons.css';\n@import '~roboto-fontface/css/roboto-fontface.css';\n@import '~material-design-lite/src/material-design-lite';\n\n// Import MDLEXT\n@import '~mdl-ext/src/mdl-ext';\n\n// ... or import mdl-ext-eqjs\n//@import '~mdl-ext/src/mdl-ext-eqjs';\n\n// 3. Your stuff\n@import 'stylesheets/variables';\n@import 'stylesheets/app/whatever';\n```\n\n**Import material-design-lite, mdl-ext and styles.scss into your main JavaScript file, e.g. `./scr/index.js`**\n```javascript\nimport 'material-design-lite/material';\nimport 'mdl-ext';\nimport './styles.scss';\n```\n\n**If you choose to use element queries, import `eq.js`**  \n```javascript\nimport eqjs from 'eq.js';\nwindow.eqjs = eqjs; // Put in global scope - for use with script in page\n```\n\n### Use of specific components in your (webpack) build\n\nIt is possible to use a selection of the provided MDLEXT components. Just import the specific MDLEXT SASS \nmodule and the corresponding ES2015 JavaScript component. The following example demonstrates a setup that uses only two \nof the MDLEXT components; menu-button and selectfield.\n\n**Import SASS files into your main SCSS file, e.g. `./src/styles.scss`**\n\n```scss\n@charset \"UTF-8\";\n\n// 1.  Configuration and helpers\n\n// MDL image path\n$image_path: '~material-design-lite/src/images';\n\n// Material Design Lite\n@import '~material-design-lite/src/variables';\n@import '~material-design-lite/src/mixins';\n\n// mdl-ext\n@import '~mdl-ext/src/variables';\n@import '~mdl-ext/src/mixins';\n@import '~mdl-ext/src/functions';\n\n// 2.  Vendors\n\n// Import MDL\n@import '~material-design-icons/iconfont/material-icons';\n@import '~roboto-fontface/css/roboto/sass/roboto-fontface-light';\n@import '~material-design-lite/src/material-design-lite';\n\n// Import required MDLEXT SASS modules\n@import '~mdl-ext/src/aria-expanded-toggle/aria-expanded-toggle';\n@import '~mdl-ext/src/menu-button/menu-button';\n@import '~mdl-ext/src/selectfield/selectfield';\n\n// 3. Your stuff\n@import 'stylesheets/variables';\n@import 'stylesheets/app/whatever';\n```\n\n**Import material-design-lite, mdl-ext components and styles.scss into your main JavaScript file, e.g. `./scr/index.js`**\n```javascript\nimport 'material-design-lite/material';\n\n// Import MDLEXT components from the es folder\nimport 'mdl-ext/es/menu-button/menu-button';\nimport 'mdl-ext/es/selectfield/selectfield';\n\nimport './styles.scss';\n```\n\nYou can find a webpack project with this setup in the [example-webpack](./example-webpack) folder. Clone this repo, cd \ninto the `example-webpack` folder. Run `npm install`, then run `npm start` and open a browser @ http://localhost:8080/\n\n\u003e**Note:** The `example-webpack` project is a stripped down version of the\n[webpack2-boilerplate](https://github.com/leifoolsen/webpack2-boilerplate) project. If you need a complete project\nsetup, start with the webpack2 boilerplate or a similar boilerplate project. \n\n \n## Components\n\n### Accordion\n![Accordion](./etc/flexbox-accordion.png)\n\nA [WAI-ARIA](https://www.w3.org/TR/wai-aria-practices-1.1/#accordion) friendly [**accordion**](./src/accordion/) \ncomponent with vertcial or horizontal layout.\n\n### Bordered fields\n![Bordered fields](./etc/bordered-fields-theme.png)\n\nThe Material Design Lite Ext (MDLEXT) [**bordered fields**](./src/bordered-fields/) component demonstrates how you \ncan create your own theme of MDL text fields.\n\n### Carousel\n![Lightbox](./etc/carousel.png)\n\nA responsive image [**carousel**](./src/carousel/).\n\n### Collapsible - Collapse All the Things\n**Collapsed**\n\n![Collapsible collapsed](./etc/collapsible-collapsed.jpg)\n\n**Expanded**\n\n![Collapsible expanded](./etc/collapsible-expanded.jpg)\n\nAccessible [**collapsible**](./src/collapsible/) content regions.\n\n### Color themes\n![Palette](./etc/palette.png)\n\nThe [**color-themes**](./src/color-themes/) component demonstrates how you can create your own themes of \n[material design colors](https://www.google.com/design/spec/style/color.html).\n\n###Formatfield\n![Formatfield](./etc/formatfield.png)\n\nThe [formatfield](./src/formatfield/) component formats an input field \nusing language sensitive number formatting.\n\n### Grid\n![Grid](./etc/grid.png)\n\nA responsive [**grid**](./src/grid) based on **element queries** in favour of media queries.\n\n### Lightboard\n![Lightboard](./etc/lightboard.png)\n\nA [**lightboard**](./src/lightboard/) is a translucent surface illuminated from behind, used for\nsituations where a shape laid upon the surface needs to be seen with high contrast. In the \"old days\"\nof photography photograpers used a lightboard to get a quick view of, sorting and organizing their slides.\n\n### Lightbox\n![Lightbox](./etc/lightbox.png)\n\nA [**lightbox**](./src/lightbox/) displays an image filling the screen, and dimming out the rest of the web page. \nIt acts as a modal dialog using the `\u003cdialog\u003e` element as a container for the lightbox.\n\n### Menu Button\n![Menu button](./etc/menu-button.png)\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp; ![Menu button](./etc/menu-button-2.png)\n\n\nA [**menu button**](./src/menu-button/) is a button that opens a menu. It has roles, attributes and behaviour as outlined in \nWAI-ARIA Authoring Practices, [2.20 Menu Button](https://www.w3.org/TR/wai-aria-practices/#menubutton).\n\n### Selectfield\n![Selectfield](./etc/select-element.png)\n\nThe Material Design Lite Ext (MDLEXT) [**select field**](./src/selectfield/) component is an enhanced version\nof the standard [HTML `\u003cselect\u003e`] (https://developer.mozilla.org/en/docs/Web/HTML/Element/select) element.\n\n### Sticky Header\n![StickyHeader](./etc/sticky-header.png)\n\nA [**sticky header**](./src/sticky-header/) makes site navigation easily accessible anywhere on the page and saves content space at the same.\n\nThe header should auto-hide, i.e. hiding the header automatically when a user starts scrolling down the page and \nbringing the header back when a user might need it: they reach the bottom of the page or start scrolling up.\n\n## Notes\n\u003eA Live demo of MDLEXT is available [here](http://leifoolsen.github.io/mdl-ext/index.html).\u003cbr/\u003e\n\u003eYou can also download or clone a demo project from here: https://github.com/leifoolsen/mdl-webpack. The demo project demonstrates\nhow you can set up MDL with Babel(6) and Webpack, and how to self host Font Roboto and Material Icons in your web application.\n\n\u003ePolyfills you might need:\n\u003e* [dialog-polyfill](https://github.com/GoogleChrome/dialog-polyfill)\n\u003e* [eqjs](https://github.com/Snugug/eq.js)\n\u003e* [custom-event polyfill](https://github.com/webmodules/custom-event) or [similar](https://github.com/leifoolsen/mdl-ext/blob/master/src/utils/custom-event-polyfill.js)\n\u003e* [mutation-observer polyfill](https://github.com/webmodules/mutation-observer)\n\u003e* [polyfill.io](https://polyfill.io/v2/docs/) \n\n### Using Material Design Lite in a Single Page Application (SPA)\nIf you use Material Design Lite in a dynamic page, e.g. a single page application, you must call \n`componentHandler.upgradeElement` and `componentHandler.downgradeElements` accordingly to properly initialize an clean up \ncomponent resources when sections of the page is updated. In a static web application there should be no need to call \n`componentHandler.downgradeElements`.\n\nThe following code snippet demonstrates how to properly clean up MDL components before removing them from DOM.\n\n```javascript\n// Call 'componentHandler.downgradeElements' to clean up\nconst content = document.querySelector('#content');\nconst components = content.querySelectorAll('.is-upgraded');\ncomponentHandler.downgradeElements([...components]);\n\n// Remove elements from DOM.\n// See: http://jsperf.com/empty-an-element/16\nconst removeChildElements = (element, forceReflow = true) =\u003e {\n  while (element.lastChild) {\n    element.removeChild(element.lastChild);\n  }\n  if(forceReflow) {\n    // See: http://jsperf.com/force-reflow\n    const d = element.style.display;\n    element.style.display = 'none';\n    element.style.display = d;\n  }\n}\n\nremoveChildElements(content); \n```\n\n\n## Licence\n© Leif Olsen, 2016. Licensed under an [Apache-2](https://github.com/leifoolsen/mdl-ext/blob/master/LICENSE) license.\n\nThis software is built with the [Google Material Design Lite](https://github.com/google/material-design-lite) framework,\nwhich is licenced under an Apache-2 licence.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fleifoolsen%2Fmdl-ext","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fleifoolsen%2Fmdl-ext","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fleifoolsen%2Fmdl-ext/lists"}