https://github.com/balmjs/balm-ui
:diamonds: A modular and customizable UI library based on Material Design and Vue
https://github.com/balmjs/balm-ui
balm css design-systems javascript material-components material-design ui-kit vue vue-components vue3 web
Last synced: 7 months ago
JSON representation
:diamonds: A modular and customizable UI library based on Material Design and Vue
- Host: GitHub
- URL: https://github.com/balmjs/balm-ui
- Owner: balmjs
- License: mit
- Created: 2016-10-17T02:43:43.000Z (about 9 years ago)
- Default Branch: main
- Last Pushed: 2025-05-06T06:21:04.000Z (7 months ago)
- Last Synced: 2025-05-13T21:13:06.272Z (7 months ago)
- Topics: balm, css, design-systems, javascript, material-components, material-design, ui-kit, vue, vue-components, vue3, web
- Language: SCSS
- Homepage: https://material.balmjs.com
- Size: 56.7 MB
- Stars: 512
- Watchers: 9
- Forks: 29
- Open Issues: 25
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
- awesome-vue - BalmUI - A modular and customizable UI library based on Material Design and Vue ` 📝 3 days ago` (Frameworks [🔝](#readme))
- awesome-vue - BalmUI - A modular and customizable UI library based on Material Design and Vue 3.0 (Components & Libraries / Frameworks)
- fucking-awesome-vue - BalmUI - A modular and customizable UI library based on Material Design and Vue 3.0 (Components & Libraries / Frameworks)
- awesome-vue - BalmUI - A modular and customizable UI library based on Material Design and Vue 3.0 (Components & Libraries / Frameworks)
README
# [BalmUI](https://material.balmjs.com/) [![BalmUI version][balm-ui-image]][balm-ui-url] [![MDC version][mdc-web-image]][mdc-web-url]
> Next Generation Material UI for Vue.js
## Introduction
[BalmUI](https://material.balmjs.com/) is a modular and customizable [Material Design](https://material.io/) UI library for Vue 3.
> [`balm-ui@8`](https://github.com/balmjs/balm-ui/tree/8.x) supports for Vue 2
## Features
- Enterprise-class UI designed for web applications
- A set of high-quality Vue components/plugins/directives/utils out of the box
- Powerful theme customization in every detail
- Integrated a complete set of the latest Material Icons
- All components and plugins is highly customizable, and can be used individually
- TypeScript support (updating)
## Documentation & Demos
- Visit [material.balmjs.com](https://material.balmjs.com/)
- Visit [v8.material.balmjs.com](https://v8.material.balmjs.com/) (for Vue 2)
## Quick Start
### Requirements
- Vue.js@3.0+
- :rocket: **[Balm CLI](https://github.com/balmjs/balm-cli)** or [Vue CLI](https://github.com/vuejs/vue-cli)/[Vite](https://github.com/vitejs/vite) or other toolchains
### 1. For Balm CLI
#### 1.0 Create a project
```sh
balm init vue my-project
cd my-project
```
#### 1.1 Installing `balm-ui`
```sh
yarn add balm-ui
# OR
npm install --save balm-ui
```
#### 1.2 Configuration
update `balm.config.js`
- get [Material Icons](https://material.balmjs.com/material-icons.zip) without downloading (or, download and extract to `my-project/app/fonts`)
```js
const api = (mix) => {
if (mix.env.isDev) {
mix.copy('node_modules/balm-ui/fonts/*', 'app/fonts');
}
};
```
- edit `my-project/config/balmrc.js` for using [Dart Sass](https://balm.js.org/docs/config/styles.html#styles-dartsass)
```js
module.exports = {
styles: {
extname: 'scss'
}
// Other Options...
};
```
#### 1.3 Usage
##### Default Usage
- edit `my-project/app/styles/global/_vendors.scss`
```scss
/* import BalmUI styles */
@use 'balm-ui/dist/balm-ui';
```
> Recommend to use Sass in `/path/to/project-name/styles/_vendors.scss`, and you can use more advanced style usage of the BalmUI.
- edit `my-project/app/scripts/main.js`
```js
import { createApp } from 'vue';
import App from '@/views/layouts/app';
import BalmUI from 'balm-ui'; // Official Google Material Components
import BalmUIPlus from 'balm-ui/dist/balm-ui-plus'; // BalmJS Team Material Components
const app = createApp(App);
app.use(BalmUI); // Mandatory
app.use(BalmUIPlus); // Optional
app.mount('#app');
```
##### Standalone Usage
- edit `my-project/app/styles/global/_vendors.scss`
```scss
@use 'balm-ui/components/core';
@use 'balm-ui/components/button/button';
@use 'balm-ui/components/icon/icon';
@use 'balm-ui/components/dialog/dialog';
@use 'balm-ui/plugins/alert/alert';
```
- edit `my-project/app/scripts/main.js`
```js
import { createApp } from 'vue';
import App from '@/views/layouts/app';
import UiButton from 'balm-ui/components/button';
import $alert from 'balm-ui/plugins/alert';
const app = createApp(App);
app.use(UiButton);
app.use($alert);
app.mount('#app');
```
#### 1.4 Development and testing
```bash
npm run dev
```
- edit a vue component: `my-project/app/scripts/views/components/hello.vue`
```html
...
Click Me
```
#### 1.5 Bundling and deployment
```bash
npm run prod
```
### 2. For Vue CLI or Vite
#### 2.0 Create a project
- `vue-cli`
```sh
vue create my-project
cd my-project
```
- `vite`
```sh
# npm 6.x
npm init @vitejs/app my-project --template vue
# npm 7+, extra double-dash is needed:
npm init @vitejs/app my-project -- --template vue
# yarn
yarn create @vitejs/app my-project --template vue
cd my-project
```
#### 2.1 Installing `balm-ui`
```sh
yarn add balm-ui
# OR
npm install --save balm-ui
```
#### 2.2 Configuration
- `vue-cli`
```js
// vue.config.js
module.exports = {
runtimeCompiler: true,
// NOTE: set alias via `configureWebpack` or `chainWebpack`
configureWebpack: {
resolve: {
alias: {
'balm-ui-plus': 'balm-ui/dist/balm-ui-plus.js',
'balm-ui-css': 'balm-ui/dist/balm-ui.css'
}
}
}
// chainWebpack: (config) => {
// config.resolve.alias
// .set('balm-ui-plus', 'balm-ui/dist/balm-ui-plus.js')
// .set('balm-ui-css', 'balm-ui/dist/balm-ui.css');
// }
};
```
- `vite`
```js
// vite.config.js
import { defineConfig } from 'vite';
import vue from '@vitejs/plugin-vue';
export default defineConfig({
plugins: [vue()],
resolve: {
alias: {
vue: 'vue/dist/vue.esm-bundler.js',
'balm-ui-plus': 'balm-ui/dist/balm-ui-plus.esm.js',
'balm-ui-css': 'balm-ui/dist/balm-ui.css'
}
}
});
```
#### 2.3 Usage
- edit `my-project/src/main.js`
```js
import { createApp } from 'vue';
import App from './App.vue';
import BalmUI from 'balm-ui'; // Official Google Material Components
import BalmUIPlus from 'balm-ui-plus'; // BalmJS Team Material Components
import 'balm-ui-css';
const app = createApp(App);
app.use(BalmUI);
app.use(BalmUIPlus);
app.mount('#app');
```
### 3. For ``
```html
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Hello BalmUI</title>
<link rel="stylesheet" href="https://unpkg.com/balm-ui/dist/balm-ui.css" />
</head>
<body>
<div id="app">
<ui-button icon="add" @click="$alert(message)">SayHi</ui-button>
</div>
<script src="https://unpkg.com/vue">
const app = Vue.createApp({
setup() {
var message = 'Hello BalmUI';
return {
message
};
}
});
app.use(BalmUI);
app.use(BalmUIPlus);
app.mount('#app');