vue-uswds
v1.9.0
Published
Vue 3 implementation of the USWDS (U.S. Web Design System) component library
Downloads
526
Maintainers
Readme
Vue USWDS
A Vue 3 implementation of the USWDS. If you need Vue 2 support, check out the USWDS-Vue library.
A Nuxt 3 integration module is available.
Documentation
Installation
Note: You will need to install the USWDS CSS separately.
Vue USWDS can be installed either by including it with a simple script
tag or using NPM and a build system.
Script Tag
The easiest way to include the library with a script tag is to use a CDN such as jsDelivr or unpkg. You can also load the library locally on your server.
When using with a script tag all components will be imported.
<script src="https://unpkg.com/vue@3"></script>
<script src="https://unpkg.com/vue-uswds"></script>
NPM (Node Package Manager)
npm install vue-uswds
// or
yarn install vue-uswds
Usage
When importing the library via NPM you can import all components or use the À La Carte method to import only specific components. The À La Carte method makes it easier to reduce the final bundle size of your application by only including components you are using.
All Components
import Vue from 'vue'
import VueUswds from 'vue-uswds'
const app = Vue.createApp({})
app.use(VueUswds, {
// ...options
})
app.mount('#app')
À La Carte
// App.vue
import Vue from 'vue'
import VueUswds from 'vue-uswds/core' // Import only the core library.
const app = Vue.createApp({})
app.use(VueUswds, {
// ...options
})
app.mount('#app')
// MyComponent.vue
<script>
import { UsaTag } from 'vue-uswds/components'
export default {
components: { UsaTag },
}
</script>
<template>
<UsaTag>My Custom Tag</UsaTag>
</template>
If there are components you wish to use anywhere in your app without first importing them, you can register them globally.
// App.vue
import Vue from 'vue'
import VueUswds from 'vue-uswds/core' // Import only the core library.
import { UsaTag } from 'vue-uswds/components'
const app = Vue.createApp({})
app.use(VueUswds, {
// ...options
})
// Register any global components...
app.component('UsaTag', UsaTag)
app.mount('#app')
Recommended IDE Setup
Contributing Guidelines
- Create an issue for any bugs or feature requests before doing any work.
- This project follows Conventional Commits naming conventions for all git commits.
- The git commit format can be easily generated by running
npm run commit
which will use Comittizen to walk you through the formatting options of your commit.
- The git commit format can be easily generated by running
- This project uses
npm
, notyarn
orpnpm
. - Prettier and ESLint are run as pre-commit hooks to help maintain a consistent code style. They are also run with any PR's submitted.
- Cypress is used for all component tests.
- All components must have tests.
- Cypress can be run locally, but will also run with all PR's.
- Tests must pass in order for PR's to be merged.
- See the "Tests" section of this README for commands to run tests locally.
- Storybook is used for documentation.
- All components must have a story.
- You can preview Storybook locally by running
npm run storybook
.
- Vue's composition API is preferred over the options API.
Testing Github Actions Locally
Use act to test Github actions locally.
Note: Because the act docker containers do not have the XVFB dependency installed, you must use a custom docker container from Cypress by adding:
container:
image: cypress/browsers:node14.17.0-chrome91-ff89
The specific container can be one of Cypress's docker images.
You may also need to temporarily adjust the node matrix versions to use the provided by the Cypress container.
Tests
Specific Cypress component tests:
node_modules/.bin/cypress run-ct --spec="src/components/UsaDatePickerCalendar/UsaDatePickerCalendar.test.js" --headed --no-exit
All Cypress component tests headless:
npm run test:component
Headed Cypress interactive component tests:
npm run cypress:open-ct