What is material-svelte?

material-svelte is a component-library for svelte implementing the material-design specification.

See it in action on our example application.

See what the components can do in our storybook.

Development Status

• material-svelte is currently in active development
• there are still many components missing, but we got a solid foundation
• APIs of existing components can be considered semi-stable, but should not be considered stable until we hit 2.0.0
• the topic of theming has yet to be solved
• the topic of configuration has yet to be solved

Design Goals

• We aim to be as close as possible to the material design specification as defined by material.io
• We aim to enable you to quickly and efficiently build your applications
• We aim to enable you to work with state-of-the-art toolchains. Our primary focus lays on integrating with SvelteKit, Vite, Snowpack
• We aim for component implementations that follow the Svelte-mindset
• We aim for being a distinct, svelte-centric implementation. We don't want to be a copy-cat of other libraries (e.g. material-ui, vuetify), which are awesome in their own right

Features

• We provide you with fully typed components
• We provide you with confidence by applying git-flow based merge-strategies with linting-, testing- and release-ci-pipelines
• We provide you with confidence by applying cross-platform, cross-browser screenshot testing powered by happo.io

Future

• We aim to provide you with confidence by having our components fully tested[1]

[1] The foundation is there. But the current test-suite can be considered smoke-test at best.

Installation

SvelteKit

Setup SvelteKit-project

(A full example is available here)

To get started: Create a SvelteKit-project.

:exclamation: Make sure to enable TypeScript-Support.

$ npm init svelte@next
npx: installed 5 in 1.269s

create-svelte version 2.0.0-next.70

Welcome to SvelteKit!

This is beta software; expect bugs and missing features.

If you encounter a problem, open an issue on https://github.com/sveltejs/kit/issues if none exists already.

✔ Which Svelte app template? › Skeleton project
✔ Use TypeScript? … No / Yes
✔ Add ESLint for code linting? … No / Yes
✔ Add Prettier for code formatting? … No / Yes
✔ Copied project files
✔ Added TypeScript support. To use it inside Svelte components, add lang="ts" to the attributes of a script tag.

Setup material-svelte PostCSS-plugin

As we use PostCSS with custom mixins, at-rules etc, you are required to configure svelte to use our PostCSS-plugin.

Install it:

$ npm install --save-dev @material-svelte/postcss-plugin

Enable it in svelte.config.js:

import preprocess from 'svelte-preprocess';
+ import materialPostcss from '@material-svelte/postcss-plugin';

/** @type {import('@sveltejs/kit').Config} */
const config = {
  // Consult https://github.com/sveltejs/svelte-preprocess
  // for more information about preprocessors
-  preprocess: preprocess(),
+  preprocess: preprocess({
+    postcss: {
+      plugins: [
+        materialPostcss(),
+      ],
+    },
+  }),

  kit: {
    // hydrate the <div id="svelte"> element in src/app.html
    target: '#svelte'
  }
};

export default config;

Vite

Setup Vite-project

(A full example is available here)

To get started: Create a Vite-Svelte-project.

:exclamation: Make sure to enable TypeScript-Support.

$ npm init @vitejs/app
✔ Project name: · vite-project
✔ Select a framework: · svelte
✔ Select a variant: · TypeScript

Scaffolding project in /tmp/vite/vite-project...

Done. Now run:

  cd vite-project
  npm install
  npm run dev

Setup material-svelte PostCSS-plugin

As we use PostCSS with custom mixins, at-rules etc, you are required to configure svelte to use our PostCSS-plugin.

Install it:

$ npm install --save-dev @material-svelte/postcss-plugin

Enable it in svelte.config.cjs:

const sveltePreprocess = require('svelte-preprocess')
+ const materialPostcss = require('@material-svelte/postcss-plugin')

module.exports = {
  // Consult https://github.com/sveltejs/svelte-preprocess
  // for more information about preprocessors
-  preprocess: sveltePreprocess()
+  preprocess: sveltePreprocess({
+    postcss: {
+      plugins: [
+        materialPostcss(),
+      ],
+    },
+  })
}

Snowpack

Setup Snowpack-Svelte-project

(A full example is available here)

To get started: Create a Snowpack-Svelte-project.

:exclamation: Make sure to use the TypeScript-enabled app-template.

$ npx create-snowpack-app snowpack-project --template @snowpack/app-template-svelte-typescript
npx: installed 24 in 3.141s

  - Using template @snowpack/app-template-svelte-typescript
  - Creating a new project in /tmp/snowpack-project
  - Installing package dependencies. This might take a couple of minutes.

...

Quickstart:

  cd snowpack-project
  npm start

All Commands:

  npm install      Install your dependencies. (We already ran this one for you!)
  npm start        Start your development server.
  npm run build    Build your website for production.
  npm test         Run your tests.

Setup material-svelte PostCSS-plugin

As we use PostCSS with custom mixins, at-rules etc, you are required to configure svelte to use our PostCSS-plugin.

Install it:

$ npm install --save-dev @material-svelte/postcss-plugin

Enable it in svelte.config.js:

const autoPreprocess = require('svelte-preprocess');
+ const materialPostcss = require('@material-svelte/postcss-plugin')

module.exports = {
  preprocess: autoPreprocess({
    defaults: {
      script: 'typescript',
    },
+    postcss: {
+      plugins: [
+        materialPostcss(),
+      ],
+    },
  }),
};

Usage

Use material-svelte components

You can either install individual component packages (e.g. @material-svelte/button) or the meta-package material-svelte[1]

$ npm install --save-dev @material-svelte/button

Then start using it in your components:

<script lang="ts">
  import { Button } from '@material-svelte/button';
</script>

<Button>Hello World</Button>

[1] We're not completely confident in the meta-package yet. From time-to-time problems arise with transitive-dependencies with individual build-tools.

Contributing

See Contributing Guide

Sponsors

Vercel

Thanks to Vercel for sponsoring this project by allowing it to run deployments for free!

happo.io

Thanks to happo.io for sponsoring this project by allowing it to run cross-platform, cross-browser screenshot-testing for free!

License

MIT