@ginger-tek/pico-vue v2.1.2

A Vue.js 3.x component library for use with the Pico 2.x CSS framework

Get Started

It is recommended to already be familiar with Pico CSS, as the components utilize the same semantic HTML, attributes, and classes. You can review the docs here if necessary.

How To Use

Which build of Vue you are using will determine how PicoVue needs to be installed and integrated.

ES Module Build (CDN)

This is the suggested way to implement PicoVue, in the spirit of building web apps the "no-tools" way ;)

1. First, add Pico and Vue via CDN:

   <link rel="stylesheet" href="https://unpkg.com/@picocss/pico@2">
   <script src="https://unpkg.com/vue@3"></script>

2. Then, import PicoVue in your module file:

   import PicoVue from 'https://unpkg.com/@ginger-tek/pico-vue@latest/pico-vue.js'

3. Finally, load PicoVue into your app via use():

   Vue.createApp(App)
     .use(PicoVue)
     .mount('#app')

Vue Compiled SFC

If you're building your Vue app via Vite or similar build-tools, you can still use PicoVue; just requires a few more steps

1. First, install PicoCSS and PicoVue from p/npm:

   npm install @picocss/pico@2 @ginger-tek/pico-vue

2. Then, import PicoCSS and your App component:

   import '@picocss/pico'
   import App from './App.vue'

3. To properly initialize PicoVue, we need to import the ESM Bundler version of Vue and make it global to simulate the ESM Module build of Vue:

   import * as Vue from 'vue/dist/vue.esm-bundler'
   window.Vue = Vue

4. Finally, import PicoVue and use() it in your app:

   import PicoVue from '@ginger-tek/pico-vue'
   
   createApp(App)
     .use(PicoVue)
     .mount('#app')

Components

All components are vanilla ESM modules that use the Vue 3 Composition API. They can be used directly in both vanilla ESM modules or Vue Single File Components (SFC)

Modal

Attributes

Events

Modals can be shown/closed either by data attributes or global helper functions.

To open a modal via a button, you can use the data-show-modal attribute, specifying the id of the modal to target:

<modal title="My Modal" id="my-modal">
  ...
</modal>
<button data-show-modal="my-modal">Open Modal</button>

To add a custom close button, add a button element with the data-close-modal attribute; no value is needed:

<modal title="My Modal" id="my-modal">
  ...
  <button type="button" data-close-modal>Close this modal</button>
</modal>

To open or close a modal programmatically, use the global window functions showModal() or closeModal(), which take the id of the target modal as an argument:

showModal('my-modal')
closeModal('my-modal')

Examples

Modal with AJAX form

<modal title="My modal form" id="my-modal-form" hide-close-x @closed="refreshData">
  <form @submit.prevent="submitForm">
    ...
    <div class="grid">
      <button type="reset" class="secondary" data-close-modal>Cancel</button>
      <button type="submit">Submit</button>
    </div>
  </form>
</modal>

async function submitForm() {
  const result = apiCall(...)
  if (result == true) closeModal('my-modal-form')
}

async function refreshData() {
  ...
}

Dropdown

Attributes

Events

Examples

<dropdown>
  <li>One</li>
  <li>Two</li>
</dropdown>

SmartTable

Attributes

Provides an interactive, responsive table with column filtering and sorting.

Columns are automatically generated based on the object properties in the array, but you can use the fields attribute to specify columns.

Examples

Simple

<smart-table :items="data" bordered></smart-table>

Specific Columns

<smart-table :items="data" :fields="fields"></smart-table>

const fields = [
  'firstname',
  'lastName',
  { name: 'createdOn', label: 'Created' },
  { name: 'invoiceTotal', label: 'Total', align: 'right' }
]

Enable Column Filtering

<smart-table :items="data" filter></smart-table>

Custom Empty Text/HTML

<smart-table :items="data">
  <template #empty-text>
    <span style="color:red">No data at all, muchacho!</span>
  </template>
</smart-table>

Custom Empty Filter Text/HTML

<smart-table :items="data" filter>
  <template #empty-filter-text>
    <i>No result for that. Try again, buddy<i>
  </template>
</smart-table>

Custom Busy Text/HTML

<smart-table :items="data" :busy="true">
  <template #busy-text>
    <span style="color:red">Hold up! We're working on it!</span>
  </template>
</smart-table>

Alert

Attributes

Alerts with no content are hidden by default, and will show when content is added

Examples

<alert type="error"></alert> <!-- hidden -->
<alert type="error">Oh no! Something went wrong!</alert> <!-- shown -->

Toaster

Attributes

A responsive component for creating toast notifications.

NOTE: Only one instance of the toaster component should be added to your application, typically in the main App component.

To add a toast programmatically, use the global window function appendToast and pass an object with any of the following options: |Name|Type|Details| |---|---|---| |content|String|Text or HTML string of content to display| |type|String|Style of the toast. Valid options are success (green) or error (red)| |dismissAfter|Number|Seconds after which the toast will auto-dismiss. Default is 5 seconds| |stay|Boolean|Disable the auto-dismiss. Toast must be closed manually|

Examples

<toaster width="400px"></toaster>
<toaster position="top-center"></toaster>

// regular (gray) toast
appendToast({ content: 'Here is a message' })
// info (cyan) toast
appendToast({ content: 'Some info...', type: 'info' })
// success (green) toast
appendToast({ content: 'Success!', type: 'success' })
// warning (yellow) toast that dismisses after 10 seconds
appendToast({ content: 'Warning!', type: 'warning', dismissAfter: 10 })
// error (red) toast that does not dismiss automatically
appendToast({ content: 'An error has occurred!', type: 'error', stay: true })

Examples

<alert type="error"></alert> <!-- hidden -->
<alert type="error">Oh no! Something went wrong!</alert> <!-- shown -->

ThemeSwitch

Attributes

Toggles and loads the value of localStorage.theme key if present. Will use to prefers-color-scheme value to determine theme on first-time load, or when localStorage.theme is cleared.

Examples

<theme-switch></theme-switch>
<theme-switch icon></theme-switch>

NavBar

Attributes

Provides a responsive navigation bar, with built-in collapsable menu.

There are 2 named slots for content. Use #brand to define your "Home"/Logo content, and #menu to define your navigable links that will responsively collapse when applicable.

Examples

<nav-bar>
  <template #brand>
    <router-link to="/">Home</router-link>
  </template>
  <template #menu>
    <li>
      <router-link to="/projects">Projects</router-link>
    </li>
    <li>
      <router-link to="/logout">Logout</router-link>
    </li>
    <li>
      <router-link to="/login">Login</router-link>
    </li>
    <li>
      <theme-switch icon> Theme</theme-switch>
    </li>
  </template>
</nav-bar>

Tabs/Tab

Tabs Attributes

Tab Attributes

Examples

<tabs>
  <tab title="My First Tab">
    ...
  </tab>
  <tab title="My Second Tab" disabled>
    ...
  </tab>
  <tab title="My Third Tab" persist>
    ...
  </tab>
</tabs>