https://github.com/crishellco/vue-spruce
A collection of useful Vue 2 renderless components.
https://github.com/crishellco/vue-spruce
Last synced: about 2 months ago
JSON representation
A collection of useful Vue 2 renderless components.
- Host: GitHub
- URL: https://github.com/crishellco/vue-spruce
- Owner: crishellco
- Created: 2021-03-12T12:19:12.000Z (about 5 years ago)
- Default Branch: master
- Last Pushed: 2026-01-19T18:15:10.000Z (about 2 months ago)
- Last Synced: 2026-01-20T00:40:40.763Z (about 2 months ago)
- Language: JavaScript
- Homepage: https://crishellco.github.io/vue-spruce/
- Size: 3.12 MB
- Stars: 3
- Watchers: 0
- Forks: 0
- Open Issues: 14
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
- awesome-vue - vue-spruce - A collection of useful Vue 2 renderless components. (Components & Libraries / UI Components)
README
# Vue Spruce
[](https://codecov.io/gh/crishellco/vue-spruce)
[](https://codeclimate.com/github/crishellco/vue-spruce/maintainability)
A collection of useful Vue 2 renderless components.
Check out the [demo](https://vue-spruce.netlify.app/)
- [Install](#install)
- [The Components](#the-components)
- [SpruceAtLeast](#spruceatleast)
- [SpruceCling](#sprucecling)
- [SpruceEvent](#spruceevent)
- [SpruceFetch](#sprucefetch)
- [SpruceFunction](#sprucefunction)
- [SprucePaginate](#sprucepaginate)
- [SpruceSearch](#sprucesearch)
- [SpruceSort](#sprucesort)
- [SpruceState](#sprucestate)
- [SpruceTagInput](#sprucetaginput)
- [SpruceToggle](#sprucetoggle)
- [SpruceWatch](#sprucewatch)
- [Examples](#examples)
- [Development](#development)
- [How to Contribute](#how-to-contribute)
- [Pull Requests](#pull-requests)
- [License](#license)
## Install
### Package
```bash
yarn add -D @crishellco/vue-spruce
# or
npm i -D @crishellco/vue-spruce
```
### Vue Plugin
Installs all components globally.
```javascript
import Vue from 'vue';
import VueSpruce from '@crishellco/vue-spruce';
Vue.use(VueSpruce);
// or with options
Vue.use(VueSpruce, { componentPrefix: 's' });
```
### Nuxt Module
Installs all components globally.
```javascript
// nuxt.config.js
{
modules: [['@crishellco/vue-spruce/nuxt', { componentPrefix: 's' }]];
}
```
#### Options
| Name | Description | Default |
|-------------------|-----------------------------------------------------|----------|
| `componentPrefix` | The prefix used when installing components globally | `spruce` |
### Named Imports
Alternatively, use only the components you need.
```javascript
import {
SpruceAtLeast,
SpruceCling,
SpruceEvent,
SpruceFetch,
SpruceFunction,
SprucePaginate,
SpruceSearch,
SpruceSort,
SpruceState,
SpruceToggle,
SpruceWatch,
} from '@crishellco/vue-spruce';
export default {
components: {
SpruceAtLeast,
SpruceCling,
SpruceEvent,
SpruceFetch,
SpruceFunction,
SprucePaginate,
SpruceSearch,
SpruceSort,
SpruceState,
SpruceToggle,
SpruceWatch,
},
};
```
## The Components
### SpruceAtLeast
Ensures a component shows for at least a given amount of time, in milliseconds, before hiding.
```html
{{ disabled ? 'waiting...' : show ? 'hide' : 'show' }}
```
#### Props
| Name | Description | Type | Required | Default |
|--------|--------------------------------------------------------------------|---------|----------|---------|
| `ms` | Minimum amount of time to show, in milliseconds | Number | Yes | |
| `show` | Weather or not to show the contents (given enough time has passed) | Boolean | No | `true` |
#### Slots
| Name | Required |
|-----------|----------|
| `default` | Yes |
#### Slot Scope
| Slot | Name | Description | Type |
|-----------|------------|------------------------------------------------------------|---------|
| `default` | `disabled` | True if waiting to hide content after `ms` time has passed | Boolean |
| `default` | `show` | If the contents should be shown | Boolean |
### SpruceCling
Clings the `clinger` slot's contents to the `anchor` slot's contents using `popper.js`. Great for things like dropdown menus. _See the [demo](https://vue-spruce.netlify.app/) for more context._
```html
i'm a button
i'm a clinger!
```
#### Props
| Name | Description | Type | Required | Default |
|-------------|------------------------------------------------------------------------------------------------------------------------------|--------|----------|---------|
| `modifiers` | The [popper.js modifiers](https://popper.js.org/docs/v2/modifiers/) | Array | No | `[]` |
| `placement` | The [popper.js placement](https://popper.js.org/docs/v2/constructors//#options) of the `clinger` in relation to the `anchor` | String | No | `auto` |
#### Slots
| Name | Required |
|-----------|----------|
| `anchor` | Yes |
| `clinger` | Yes |
#### Slot Scope
| Slot | Name | Description | Type |
|-----------|----------|-----------------------------|----------|
| `anchor` | `update` | Updates the popper instance | Function |
| `clinger` | `update` | Updates the popper instance | Function |
### SpruceEvent
Track any `window` event occurance inside or outside of `SpruceEvent`'s default slot.
```html
Hover over me!
```
#### Props
| Name | Description | Type | Required | Default |
|-------------|---------------------------------------------------------------|---------|----------|---------|
| `event` | The event to listen to | String | Yes | |
| `immediate` | First event immediately (in `mounted`) | Boolean | No | `false` |
| `outside` | Listen for the even only outside of the default slot elements | Boolean | No | `false` |
#### Events
| Name | Description | Payload |
|----------------------------|-------------------------------|---------|
| _Same as the `event` prop_ | Fired when the event happens. | -- |
#### Slots
| Name | Required |
|-----------|----------|
| `default` | No |
### SpruceFetch
Make asynchronous API fetch calls.
```html
Errors! {{ error.status }}
Data: {{ data }}
Refetch
```
#### Props
| Name | Description | Type | Required | Default |
|-------------|------------------------------------------------------------|---------|----------|---------|
| `url` | The API url (changing this will refetch and rest all data) | String | Yes | |
| `immediate` | Weather to immediate make the request on mount | Boolean | No | `true` |
#### Events
| Name | Description | Payload |
|-----------|--------------------------------------|-----------------------------------|
| `success` | Fires when the request is successful | `{data: Object, fetch: Function}` |
| `error` | Fires when the request fails | `{data: Object, fetch: Function}` |
#### Slots
| Name | Required |
|-----------|----------|
| `default` | Yes |
#### Slot Scope
| Slot | Name | Description | Type |
|-----------|-----------|--------------------------------------|------------------------------------|
| `default` | `calls` | Number of calls made | Number |
| `default` | `data` | The response on a successful request | Object |
| `default` | `error` | The response on a failed request | `{ data: Object, status: Number }` |
| `default` | `loading` | Whether a request is in progress | Boolean |
| `default` | `fetch` | Makes another request | Function |
### SpruceFunction
Create reusable functions on the fly (great for lists!).
```html
Click me!
```
#### Props
| Name | Description | Type | Required | Default |
|------|--------------|----------|----------|---------|
| `fn` | The function | Function | Yes | |
#### Slots
| Name | Required |
|-----------|----------|
| `default` | Yes |
#### Slot Scope
| Slot | Name | Description | Type |
|-----------|------|--------------|----------|
| `default` | `fn` | The function | Function |
### SprucePaginate
Paginate an array and navigate through it's chunks.
```html
prev
Page: {{ pageNum }}/{{ totalPages }}
Showing: {{ rangeStart }} - {{ rangeEnd }} of {{ states.length }}
next
```
#### Props
| Name | Description | Type | Required | Default |
|--------|-----------------------|------------|----------|---------|
| `size` | Page size | Number | Yes | |
| `list` | The items to paginate | Array | Yes | |
#### Slots
| Name | Required |
|-----------|----------|
| `default` | Yes |
#### Slot Scope
| Slot | Name | Description | Type |
|-----------|--------------|-----------------------------------------------------------------------------------------------|----------|
| `default` | `first` | Go to first page | Function |
| `default` | `go` | Go to specific page | Function |
| `default` | `isFirst` | If currently on first page | Boolean |
| `default` | `isLast` | If currently on last page | Boolean |
| `default` | `last` | Go to last page | Function |
| `default` | `next` | Go to next page | Function |
| `default` | `page` | The current page | any |
| `default` | `pages` | The chunked pages | Array |
| `default` | `links` | A calculated array of specific page numbers that can be used for links `[1, 2, 3, '...', 40]` | Array |
| `default` | `pageNum` | The current page number | Number |
| `default` | `prev` | Go to previous page | Function |
| `default` | `rangeEnd` | The end of the current page | Number |
| `default` | `rangeStart` | The start of the current page | Number |
| `default` | `reset` | Reset the state of pagination | Function |
| `default` | `totalPages` | Total number of pages | Number |
### SpruceSearch
Search an array of strings or objects by keys using [fuse.js](https://fusejs.io/).
```html
{{ item }}
```
#### Props
| Name | Description | Type | Required | Default |
|-------------|-------------------------|--------|----------|-----------------------------------------------------------------------------------|
| `keys` | The keys to search in | Array | No | If `list` is `Array` then all of the first object's keys. Otherwise `[]`. |
| `list` | The list to search | Array | Yes | |
| `term` | The terms to search for | String | No | '' |
| `threshold` | Fuse.js match threshold | Float | No | 0.6 |
#### Slots
| Name | Required |
|-----------|----------|
| `default` | Yes |
#### Slot Scope
| Slot | Name | Description | Type |
|-----------|-----------|-------------------|-------|
| `default` | `results` | The searched list | Array |
### SpruceSort
Sort an array of strings or objects in either direction by specific keys.
_Note: string sorting is case insensitive._
```html
{{ item }}
```
#### Props
| Name | Description | Type | Required | Default |
|-------------|-------------------------------------------|--------|----------|---------|
| `list` | The list to search | Array | Yes | |
| `direction` | The direction to sort in, 'asc' or 'desc' | String | No | 'asc' |
| `by` | The object property to sort by | String | No | '' |
#### Events
| Name | Description | Payload |
|----------|---------------------------------------------------|-----------|
| `change` | Fired when `results` change (the list is sorted). | `results` |
#### Slots
| Name | Required |
|-----------|----------|
| `default` | Yes |
#### Slot Scope
| Slot | Name | Description | Type |
|-----------|-----------|-------------------|-----------------------|
| `default` | `results` | The searched list | Array |
### SpruceState
Create and manage localized state.
```html
Increment ({{ count }})
```
#### Props
| Name | Description | Type | Required | Default |
|---------|------------------|--------|----------|---------|
| `value` | The state object | Object | Yes | |
#### Events
| Name | Description | Payload |
|---------|--------------------------|---------|
| `input` | Fired when state updates | `state` |
#### Slots
| Name | Required |
|-----------|----------|
| `default` | Yes |
#### Slot Scope
| Slot | Name | Description | Type |
|-----------|-----------------|--------------------------------------------|----------|
| `default` | `[key]` | Each key in the `state` prop | Any |
| `default` | `set(newValue)` | Merges `newValue` with the current `state` | Function |
### SpruceTagInput
Renderless tag input.
```html
{{ tag }}
×
export default {
data() {
return { colors: ['red', 'blue'] };
},
methods: {
validator(tag) {
return /^[a-zA-Z]+$/.test(tag);
},
},
};
```
#### Props
| Name | Description | Type | Required | Default |
|-------------------|-------------------------------------------------------------------------------------------------------------------------------|----------|----------|--------------|
| `allowDuplicates` | Allows duplicate tags | Boolean | No | `False` |
| `allowPaste` | Allows pasting to automatically create tags | Boolean | No | `False` |
| `disabled` | Disables all interactions | Boolean | No | `False` |
| `keepOnBackspace` | Disables deleting last tab on `keyup.backspace` in the input | Boolean | No | `False` |
| `maxTags` | Number of allowed tags | Number | No | `Null` |
| `separator` | Separator used to process pasted tags | String | No | `\t` |
| `v-model` | The tags | Array | Yes | |
| `validator` | Function that receives the String argument `tag` and returns `true` or `false` to determine the validity of the input's value | Function | No | `() => true` |
#### Slot Scope
| Slot | Name | Description | Type |
|-----------|-------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|
| `default` | `events` | Events to listen for on the input. `input` for binding value, `keydown.backspace` for delete last tag, `keydown.enter` for adding new unique tag, and `keydown.escape` for clearing input. | Object |
| `default` | `focusedTagIndex` | Currently focused tag index (to be removed on next `keydown.backspace`). Used for styling. | String |
| `default` | `remove()` | Removes a tag | Function |
| `default` | `state` | State to bind to the input. `value` of the input. | Object |
| `default` | `tags` | Array of tags | Array |
### SpruceToggle
Toggle between on (`true`) and off (`false`).
```html
Accordion header
{{ isOn ? '▲' : '▼' }}
Accordion content
Open
Close
```
#### Props
| Name | Description | Type | Required | Default |
|---------|-------------------------|---------|----------|---------|
| `value` | The state of the toggle | Boolean | No | `False` |
#### Events
| Name | Description | Payload |
|---------|---------------------------|---------|
| `input` | Fired when `isOn` updates | `isOn` |
#### Slots
| Name | Required |
|-----------|----------|
| `default` | Yes |
#### Slot Scope
| Slot | Name | Description | Type |
|-----------|------------|-------------------------|----------|
| `default` | `isOn` | The state of the toggle | Boolean |
| `default` | `on()` | Sets `isOn` to `true` | Function |
| `default` | `off()` | Sets `isOn` to `false` | Function |
| `default` | `toggle()` | Toggles `isOn` | Function |
### SpruceWatch
Watches variables for changes and emits events when changes occur.
```html
count++ ({{ count }})
```
#### Props
| Name | Description | Type | Required | Default |
|---------|--------------------------|--------|----------|---------|
| `watch` | Values you wish to watch | Object | Yes | |
#### Events
| Name | Description | Payload |
|-----------------|------------------------------------------------|------------------------------------------|
| `changed` | Fired when any value in `watch` changes | `{key: count, oldValue: 0, newValue: 1}` |
| `changed:[key]` | Fired when a specific value in `watch` changes | `{oldValue: 0, newValue: 1}` |
#### Slots
| Name | Required |
|-----------|----------|
| `default` | No |
## Examples
See the [demo source code](src/demo/components) for real-world examples. Check out the [demo](https://vue-spruce.netlify.app/) to see the components in action with code examples.
## Development
### Lint
```bash
yarn lint
```
### Test
```bash
yarn test:unit
```
### Build Dist
```bash
yarn build
```
### Run Demo
```bash
yarn serve
```
### Build Demo
```bash
yarn build:demo
```
## How to Contribute
### Pull Requests
1. Fork the repository
2. Create a new branch for each feature or improvement
3. Send a pull request from each feature branch to the **develop** branch
## License
[MIT](http://opensource.org/licenses/MIT)