{"id":13440367,"url":"https://github.com/balmjs/balm-ui","last_synced_at":"2025-05-14T20:08:22.786Z","repository":{"id":37432060,"uuid":"71093846","full_name":"balmjs/balm-ui","owner":"balmjs","description":":diamonds: A modular and customizable UI library based on Material Design and Vue","archived":false,"fork":false,"pushed_at":"2025-05-06T06:21:04.000Z","size":59499,"stargazers_count":512,"open_issues_count":25,"forks_count":29,"subscribers_count":9,"default_branch":"main","last_synced_at":"2025-05-13T21:13:06.272Z","etag":null,"topics":["balm","css","design-systems","javascript","material-components","material-design","ui-kit","vue","vue-components","vue3","web"],"latest_commit_sha":null,"homepage":"https://material.balmjs.com","language":"SCSS","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/balmjs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"open_collective":"balmjs","patreon":"balmjs","custom":["https://material.balmjs.com/donate"]}},"created_at":"2016-10-17T02:43:43.000Z","updated_at":"2025-05-07T03:35:36.000Z","dependencies_parsed_at":"2023-02-01T15:31:15.445Z","dependency_job_id":"220a0a76-58f3-4ac5-a722-f7f63d45b3f9","html_url":"https://github.com/balmjs/balm-ui","commit_stats":{"total_commits":2943,"total_committers":15,"mean_commits":196.2,"dds":"0.020387359836901098","last_synced_commit":"638972112989a412c698dd115f5915597de0dd32"},"previous_names":["balmjs/ui-vue"],"tags_count":311,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/balmjs%2Fbalm-ui","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/balmjs%2Fbalm-ui/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/balmjs%2Fbalm-ui/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/balmjs%2Fbalm-ui/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/balmjs","download_url":"https://codeload.github.com/balmjs/balm-ui/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254069220,"owners_count":22009513,"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":["balm","css","design-systems","javascript","material-components","material-design","ui-kit","vue","vue-components","vue3","web"],"created_at":"2024-07-31T03:01:22.118Z","updated_at":"2025-05-14T20:08:22.747Z","avatar_url":"https://github.com/balmjs.png","language":"SCSS","funding_links":["https://opencollective.com/balmjs","https://patreon.com/balmjs","https://material.balmjs.com/donate"],"categories":["SCSS","Components \u0026 Libraries","Frameworks [🔝](#readme)"],"sub_categories":["Frameworks"],"readme":"# [BalmUI](https://material.balmjs.com/) [![BalmUI version][balm-ui-image]][balm-ui-url] [![MDC version][mdc-web-image]][mdc-web-url]\n\n\u003e Next Generation Material UI for Vue.js\n\n## Introduction\n\n[BalmUI](https://material.balmjs.com/) is a modular and customizable [Material Design](https://material.io/) UI library for Vue 3.\n\n\u003e [`balm-ui@8`](https://github.com/balmjs/balm-ui/tree/8.x) supports for Vue 2\n\n## Features\n\n- Enterprise-class UI designed for web applications\n- A set of high-quality Vue components/plugins/directives/utils out of the box\n- Powerful theme customization in every detail\n- Integrated a complete set of the latest Material Icons\n- All components and plugins is highly customizable, and can be used individually\n- TypeScript support (updating)\n\n## Documentation \u0026 Demos\n\n- Visit [material.balmjs.com](https://material.balmjs.com/)\n- Visit [v8.material.balmjs.com](https://v8.material.balmjs.com/) (for Vue 2)\n\n## Quick Start\n\n### Requirements\n\n- Vue.js@3.0+\n- :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\n\n### 1. For Balm CLI\n\n#### 1.0 Create a project\n\n```sh\nbalm init vue my-project\ncd my-project\n```\n\n#### 1.1 Installing `balm-ui`\n\n```sh\nyarn add balm-ui\n# OR\nnpm install --save balm-ui\n```\n\n#### 1.2 Configuration\n\nupdate `balm.config.js`\n\n- get [Material Icons](https://material.balmjs.com/material-icons.zip) without downloading (or, download and extract to `my-project/app/fonts`)\n\n  ```js\n  const api = (mix) =\u003e {\n    if (mix.env.isDev) {\n      mix.copy('node_modules/balm-ui/fonts/*', 'app/fonts');\n    }\n  };\n  ```\n\n- edit `my-project/config/balmrc.js` for using [Dart Sass](https://balm.js.org/docs/config/styles.html#styles-dartsass)\n\n  ```js\n  module.exports = {\n    styles: {\n      extname: 'scss'\n    }\n    // Other Options...\n  };\n  ```\n\n#### 1.3 Usage\n\n##### Default Usage\n\n- edit `my-project/app/styles/global/_vendors.scss`\n\n  ```scss\n  /* import BalmUI styles */\n  @use 'balm-ui/dist/balm-ui';\n  ```\n\n  \u003e Recommend to use Sass in `/path/to/project-name/styles/_vendors.scss`, and you can use more advanced style usage of the BalmUI.\n\n- edit `my-project/app/scripts/main.js`\n\n  ```js\n  import { createApp } from 'vue';\n  import App from '@/views/layouts/app';\n  import BalmUI from 'balm-ui'; // Official Google Material Components\n  import BalmUIPlus from 'balm-ui/dist/balm-ui-plus'; // BalmJS Team Material Components\n\n  const app = createApp(App);\n\n  app.use(BalmUI); // Mandatory\n  app.use(BalmUIPlus); // Optional\n\n  app.mount('#app');\n  ```\n\n##### Standalone Usage\n\n- edit `my-project/app/styles/global/_vendors.scss`\n\n  ```scss\n  @use 'balm-ui/components/core';\n  @use 'balm-ui/components/button/button';\n  @use 'balm-ui/components/icon/icon';\n  @use 'balm-ui/components/dialog/dialog';\n  @use 'balm-ui/plugins/alert/alert';\n  ```\n\n- edit `my-project/app/scripts/main.js`\n\n  ```js\n  import { createApp } from 'vue';\n  import App from '@/views/layouts/app';\n  import UiButton from 'balm-ui/components/button';\n  import $alert from 'balm-ui/plugins/alert';\n\n  const app = createApp(App);\n\n  app.use(UiButton);\n  app.use($alert);\n\n  app.mount('#app');\n  ```\n\n#### 1.4 Development and testing\n\n```bash\nnpm run dev\n```\n\n- edit a vue component: `my-project/app/scripts/views/components/hello.vue`\n\n  ```html\n  \u003ctemplate\u003e\n    \u003cdiv class=\"hello\"\u003e\n      ...\n      \u003c!-- Add a test button --\u003e\n      \u003cui-button @click=\"$alert('Hello BalmUI')\"\u003eClick Me\u003c/ui-button\u003e\n    \u003c/div\u003e\n  \u003c/template\u003e\n  ```\n\n#### 1.5 Bundling and deployment\n\n```bash\nnpm run prod\n```\n\n### 2. For Vue CLI or Vite\n\n#### 2.0 Create a project\n\n- `vue-cli`\n\n  ```sh\n  vue create my-project\n\n  cd my-project\n  ```\n\n- `vite`\n\n  ```sh\n  # npm 6.x\n  npm init @vitejs/app my-project --template vue\n\n  # npm 7+, extra double-dash is needed:\n  npm init @vitejs/app my-project -- --template vue\n\n  # yarn\n  yarn create @vitejs/app my-project --template vue\n\n  cd my-project\n  ```\n\n#### 2.1 Installing `balm-ui`\n\n```sh\nyarn add balm-ui\n# OR\nnpm install --save balm-ui\n```\n\n#### 2.2 Configuration\n\n- `vue-cli`\n\n  ```js\n  // vue.config.js\n  module.exports = {\n    runtimeCompiler: true,\n    // NOTE: set alias via `configureWebpack` or `chainWebpack`\n    configureWebpack: {\n      resolve: {\n        alias: {\n          'balm-ui-plus': 'balm-ui/dist/balm-ui-plus.js',\n          'balm-ui-css': 'balm-ui/dist/balm-ui.css'\n        }\n      }\n    }\n    // chainWebpack: (config) =\u003e {\n    //   config.resolve.alias\n    //     .set('balm-ui-plus', 'balm-ui/dist/balm-ui-plus.js')\n    //     .set('balm-ui-css', 'balm-ui/dist/balm-ui.css');\n    // }\n  };\n  ```\n\n- `vite`\n\n  ```js\n  // vite.config.js\n  import { defineConfig } from 'vite';\n  import vue from '@vitejs/plugin-vue';\n\n  export default defineConfig({\n    plugins: [vue()],\n    resolve: {\n      alias: {\n        vue: 'vue/dist/vue.esm-bundler.js',\n        'balm-ui-plus': 'balm-ui/dist/balm-ui-plus.esm.js',\n        'balm-ui-css': 'balm-ui/dist/balm-ui.css'\n      }\n    }\n  });\n  ```\n\n#### 2.3 Usage\n\n- edit `my-project/src/main.js`\n\n  ```js\n  import { createApp } from 'vue';\n  import App from './App.vue';\n\n  import BalmUI from 'balm-ui'; // Official Google Material Components\n  import BalmUIPlus from 'balm-ui-plus'; // BalmJS Team Material Components\n  import 'balm-ui-css';\n\n  const app = createApp(App);\n\n  app.use(BalmUI);\n  app.use(BalmUIPlus);\n\n  app.mount('#app');\n  ```\n\n### 3. For `\u003cscript\u003e`\n\n```html\n\u003c!DOCTYPE html\u003e\n\u003chtml lang=\"en\"\u003e\n  \u003chead\u003e\n    \u003cmeta charset=\"UTF-8\" /\u003e\n    \u003cmeta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\" /\u003e\n    \u003ctitle\u003eHello BalmUI\u003c/title\u003e\n    \u003clink rel=\"stylesheet\" href=\"https://unpkg.com/balm-ui/dist/balm-ui.css\" /\u003e\n  \u003c/head\u003e\n  \u003cbody\u003e\n    \u003cdiv id=\"app\"\u003e\n      \u003cui-button icon=\"add\" @click=\"$alert(message)\"\u003eSayHi\u003c/ui-button\u003e\n    \u003c/div\u003e\n    \u003cscript src=\"https://unpkg.com/vue\"\u003e\u003c/script\u003e\n    \u003cscript src=\"https://unpkg.com/balm-ui\"\u003e\u003c/script\u003e\n    \u003cscript src=\"https://unpkg.com/balm-ui/dist/balm-ui-plus.js\"\u003e\u003c/script\u003e\n    \u003cscript\u003e\n      const app = Vue.createApp({\n        setup() {\n          var message = 'Hello BalmUI';\n\n          return {\n            message\n          };\n        }\n      });\n\n      app.use(BalmUI);\n      app.use(BalmUIPlus);\n\n      app.mount('#app');\n    \u003c/script\u003e\n  \u003c/body\u003e\n\u003c/html\u003e\n```\n\nEnjoy 👻\n\n## Contributing\n\nWe'd love for you to contribute and make BalmUI even better than it is today! Please make sure to read the [Contributing Guide](https://github.com/balmjs/balm-ui/blob/main/CONTRIBUTING.md) before making a pull request. You can submit any ideas as [pull requests](https://github.com/balmjs/balm-ui/pulls) or as [GitHub issues](https://github.com/balmjs/balm-ui/issues).\n\n## Browser support\n\nWe officially support the last two versions of every major browser. Specifically, we test on the following browsers:\n\n- **Chrome** on Android, Windows, macOS, and Linux\n- **Firefox** on Windows, macOS, and Linux\n- **Safari** on iOS and macOS\n- **Edge** on Windows\n\n## Special Thanks to\n\n- [BalmJS](https://balm.js.org/)\n- [Vue.js](https://vuejs.org/)\n- [MDC Web](https://github.com/material-components/material-components-web)\n\n[balm-ui-image]: https://img.shields.io/npm/v/balm-ui\n[balm-ui-url]: https://www.npmjs.com/package/balm-ui\n[mdc-web-image]: https://img.shields.io/badge/mdc--web-14.0.0-blue.svg\n[mdc-web-url]: https://www.npmjs.com/package/material-components-web\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbalmjs%2Fbalm-ui","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbalmjs%2Fbalm-ui","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbalmjs%2Fbalm-ui/lists"}