monobill-mintui

v0.3.76

Published

9 days ago

A modern framework-agnostic UI kit built as Web Components. Requires Tailwind CSS.

0High
0Medium
0Low

ron-vnox

web-components custom-elements ui-kit framework-agnostic vue react angular svelte tailwind components

MintUI

A modern framework-agnostic UI kit built as pure JavaScript Web Components (no framework dependencies). Works in Vue, React, Angular, Svelte, or vanilla JavaScript!

100% Framework Independent: Components are built with pure JavaScript and native Web Component APIs. No Vue, React, or any other framework required!

Requires Tailwind CSS: Components use Tailwind CSS classes and require Tailwind to be installed in your project. This ensures optimal tree-shaking and minimal CSS output.

Installation

npm install monobill-mintui

⚠️ IMPORTANT: Tailwind Configuration Required

After installing, you MUST configure Tailwind CSS to scan the mintui package files. Without this, Tailwind classes won't work!

Basic Configuration

Add this to your tailwind.config.js:

import mintuiPreset from 'monobill-mintui/tailwind-preset'

export default {
  presets: [mintuiPreset], // ⚠️ REQUIRED: Enforces dark mode color (#0A0A0A)
  content: [
    "./src/**/*.{vue,js,ts,jsx,tsx,html}",
    "./node_modules/monobill-mintui/dist/**/*.js", // ⚠️ REQUIRED: Add this line
  ],
  // ... rest of your config
}

CommonJS format:

const mintuiPreset = require('monobill-mintui/tailwind-preset')

module.exports = {
  presets: [mintuiPreset], // ⚠️ REQUIRED: Enforces dark mode color (#0A0A0A)
  content: [
    "./src/**/*.{vue,js,ts,jsx,tsx,html}",
    "./node_modules/monobill-mintui/dist/**/*.js", // ⚠️ REQUIRED: Add this line
  ],
  // ... rest of your config
}

After updating your Tailwind config, rebuild your CSS (restart your dev server or rebuild your Tailwind output).

Dark Mode Color

The mintui preset enforces the base dark mode color #0A0A0A for gray-900. This ensures consistent dark mode styling across all apps using mintui. The preset automatically sets this color, so all components will use the correct dark mode background.

Icon Configuration

Icons are loaded from SVG files. By default, icons load from the CDN at https://assets.gomonobill.com/mintui/icons/ for optimal caching and performance.

Configuring Icon Source

You can configure where icons are loaded from using a meta tag:

Default (CDN):

<!-- Icons load from CDN by default -->
<mint-icon name="caret-up"></mint-icon>

Load from Local Server:

<meta name="mint-icon-base-url" content="local">

Load from Custom Endpoint:

<meta name="mint-icon-base-url" content="/custom/path/to/icons">
<!-- or -->
<meta name="mint-icon-base-url" content="https://your-cdn.com/icons">

Explicitly Use CDN:

<meta name="mint-icon-base-url" content="cdn">

Icon Files Setup

If using local icons, ensure SVG files are available in your public/icons/ directory. The icon component expects files named like /icons/caret-up.svg, /icons/caret-down.svg, etc.

Usage

Framework-Agnostic Web Components

Components are Web Components (Custom Elements) that work in any framework:

Vanilla JavaScript / HTML

<!DOCTYPE html>
<html>
<head>
  <script type="module">
    import 'monobill-mintui'
  </script>
</head>
<body>
  <mint-button variant="primary">Click me</mint-button>
  <mint-switch id="mySwitch"></mint-switch>
  
  <script>
    document.getElementById('mySwitch').addEventListener('change', (e) => {
      console.log('Toggled:', e.detail.checked)
    })
  </script>
</body>
</html>

Vue 3

⚠️ IMPORTANT: Configure Vue to recognize custom elements

You must configure Vue to treat mint-* elements as custom elements, not Vue components.

For Vite projects, add this to your vite.config.js or vite.config.ts:

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'

export default defineConfig({
  plugins: [
    vue({
      template: {
        compilerOptions: {
          isCustomElement: (tag) => tag.startsWith('mint-'),
        },
      },
    }),
  ],
})

For Vue CLI projects, add this to your vue.config.js:

module.exports = {
  chainWebpack: (config) => {
    config.module
      .rule('vue')
      .use('vue-loader')
      .tap((options) => {
        options.compilerOptions = {
          ...options.compilerOptions,
          isCustomElement: (tag) => tag.startsWith('mint-'),
        }
        return options
      })
  },
}

For Nuxt 3, add this to your nuxt.config.ts:

export default defineNuxtConfig({
  vue: {
    compilerOptions: {
      isCustomElement: (tag) => tag.startsWith('mint-'),
    },
  },
})

Usage example:

<template>
  <mint-button variant="primary" @click="handleClick">
    Click me
  </mint-button>
  <mint-switch :checked="enabled" @change="handleChange" />
  <mint-input label="Name" v-model="name" />
  <mint-select label="Country" v-model="country">
    <option value="us">United States</option>
    <option value="ca">Canada</option>
  </mint-select>
</template>

<script setup>
import { ref } from 'vue'
import 'monobill-mintui'

const enabled = ref(false)
const name = ref('')
const country = ref('')

const handleClick = () => console.log('Clicked!')
const handleChange = (e) => {
  enabled.value = e.detail?.checked ?? e.target.checked
}
</script>

React

import { useState } from 'react'
import 'monobill-mintui'

function App() {
  const [enabled, setEnabled] = useState(false)

  return (
    <>
      <mint-button variant="primary" onClick={() => console.log('Clicked!')}>
        Click me
      </mint-button>
      <mint-switch 
        checked={enabled}
        onChange={(e) => setEnabled(e.detail?.checked ?? e.target.checked)}
      />
      <mint-input label="Name" />
      <mint-select label="Country">
        <option value="us">United States</option>
        <option value="ca">Canada</option>
      </mint-select>
    </>
  )
}

Angular

import { Component } from '@angular/core'
import 'monobill-mintui'

@Component({
  selector: 'app-root',
  template: `
    <mint-button variant="primary" (click)="handleClick()">
      Click me
    </mint-button>
    <mint-switch [checked]="enabled" (change)="handleChange($event)">
    </mint-switch>
  `
})
export class AppComponent {
  enabled = false
  handleClick() { console.log('Clicked!') }
  handleChange(e: any) { 
    this.enabled = e.detail?.checked ?? e.target.checked 
  }
}

Available Components

mint-button - Button component with multiple variants
mint-switch - Toggle switch component
mint-input - Text input, textarea, and various input types
mint-select - Select dropdown component
mint-checkbox - Checkbox component
mint-choice - Radio button group component (parent container with mint-choice-option children)
mint-tags - Tags input component with add/remove and sorting capabilities
mint-date-picker - Date picker component
mint-dropzone - File upload component
mint-form - Form component with validation
mint-icon - Icon component
mint-text - Text component with typography variants
mint-card - Card component
mint-modal - Modal dialog component
mint-popover - Popover component
mint-spinner - Loading spinner component
mint-stack - Stack layout component
mint-grid - Grid layout component
mint-page - Page container component
mint-link - Link component
mint-back-button - Back button component

Requirements

Tailwind CSS - Required. Components use Tailwind utility classes.
No framework required! Components are pure JavaScript Web Components
No JavaScript dependencies! Built with native Web Component APIs
Modern browser with Web Components support (all modern browsers)

⚠️ Critical: Tailwind Configuration

You MUST add the mintui package to your Tailwind content paths AND use the preset, otherwise the classes won't be included in your CSS and dark mode colors won't be correct:

// tailwind.config.js (ES modules)
import mintuiPreset from 'monobill-mintui/tailwind-preset'

export default {
  presets: [mintuiPreset], // ⚠️ REQUIRED: Enforces dark mode color (#0A0A0A)
  content: [
    "./src/**/*.{vue,js,ts,jsx,tsx,html}",
    "./node_modules/monobill-mintui/dist/**/*.js", // ⚠️ REQUIRED
  ],
  // ... rest of your config
}

// tailwind.config.js (CommonJS)
const mintuiPreset = require('monobill-mintui/tailwind-preset')

module.exports = {
  presets: [mintuiPreset], // ⚠️ REQUIRED: Enforces dark mode color (#0A0A0A)
  content: [
    "./src/**/*.{vue,js,ts,jsx,tsx,html}",
    "./node_modules/monobill-mintui/dist/**/*.js", // ⚠️ REQUIRED
  ],
  // ... rest of your config
}