vue-composable

Out-of-the-box ready to use composables

• 🌴 TreeShakable
• 🧙‍♂️ Fully Typescript
• 💚 Vue 3 and 2 support
• 🔨 Vue Devtools support

Introduction

This library aim is to be one stop shop for many real-world composable functions, with aggressive tree-shaking to keep it light on your end code.

Installing

# @vue/composition-api
install with yarn
yarn add @vue/composition-api vue-composable
install with npm
npm install @vue/composition-api vue-composable
vue 3
install with yarn
yarn add vue-composable
install with npm
npm install vue-composable

Documentation

Check our documentation

Composable

Event

• Event - Attach event listener to a DOM element
• Mouse Move - Attach mousemove listener to a DOM element
• Resize - Attach resize listener to a DOM element
• Scroll - Attach scroll listener to a DOM element
• onOutsidePress - Execute callback when click is outside of element

Dom

• Mouse distance from Element - Distance in pixels from an element center

Date

• useNow : Return reactive custom timer with specified refresh rate
• useDateNow : Returns reactive Date.now() with custom refresh rate
• usePerformanceNow : Returns reactive performance.now() with custom refresh rate

Format

• format - Reactive string format
• path - Retrieve object value based on string path

Breakpoint

• MatchMedia - reactive MatchMedia
• Breakpoint - reactive breakpoints based on window.innerWidth
• Chrome - reactive chrome breakpoints
• TailwindCSS - reactive TailwindCSS breakpoints

MISC

• sharedRef - cross-tab reactive ref
• VModel - helper to wrap model update into a ref [vue3 only]
• injectFactory - same as inject but allows you to have a factory as default value
• interval - self-remove setInterval on unmount
• lockScroll - lock-scroll component
• refDebounced - debounces the update value of a ref

Storage

• WebStorage - Reactive access to Storage API, useLocalStorage and useSessionStorage use this
• storage - uses localStorage or on safari private it uses sessionStorage
• localStorage - Reactive access to a localStorage
• sessionStorage - Reactive access to a sessionStorage

Pagination

• Pagination - Generic reactive pagination controls
• Array Pagination - Array pagination

Validation

• Validation - model based validation inspired by vuelidate

i18n

• i18n - Simple i18n implementation with API inspired by vue-i18n

Intl

• dateTimeFormat - Intl.DateTimeFormat
• numberFormat - Intl.NumberFormat
• currencyFormat - CurrencyFormat with Intl.NumberFormat

Promise

• Promise - Promise reactive resolve and reject
• promiseLazy - Sugar for usePromise lazy:true
• Cancellable Promise - Allow to cancel promises
• Retry - Provides functionality to retry promise

Meta

• Title - reactive document.title

State

• Timeline - Tracks variable history
• Undo - Tracks variable history, to allow undo and redo
• valueSync - syncs variables value, across multiple refs

Web

• Fetch - reactive fetch wrapper
• WebSocket - reactive WebSocket wrapper
• IntersectionObserver - reactive IntersectionObserver
• NetworkInformation - reactive NetworkInformation wrapper
• Online/online>) - reactive navigator.onLine wrapper
• PageVisibility - reactive Page Visibility API
• Language - reactive NavigatorLanguage
• BroadcastChannel - reactive BroadcastChannel API
• Geolocation API
• CSS variables - reactive CSS variables
• Worker - Web Worker API
• WorkerFunction - Webworker Function, offload a function to webworker
• share - WebShare API
• Clipboard - Clipboard API

External

New packages needed

• Axios - @vue-composable/axios reactive axios wrapper client
• makeAxios - @vue-composable/axios wrap your axios instance
• useCookie - @vue-composable/cookie js-cookie wrapper

Information

This is a monorepo project, please check packages

Devtools

There's some experimental devtools support starting from 1.0.0-beta.6, only available for vue-next and devtools beta 6.

• devtools beta chrome

Install plugin

To use devtools you need to install the plugin first:

import { createApp } from "vue";
import { VueComposableDevtools } from "vue-composable";
import App from "./App.vue";
const app = createApp(App); app.use(VueComposableDevtools); // or app.use(VueComposableDevtools, {   id: "vue-composable",   label: "devtool composables" });
app.mount("#app");

Component State

To add properties to the component inspector tab ComponentState

const bar = "bar";
useDevtoolsComponentState(
  {
    bar
  },
  {
    type: "custom composable" // change group
  }
);
const baz = () => "baz"; useDevtoolsComponentState({ baz }); // no duplicates added by default useDevtoolsComponentState({ baz });
const the = 42; useDevtoolsComponentState({ the }); // to allow multiple same key useDevtoolsComponentState({ the }, { duplicate: true });
// use a devtools api list directly interface StateBase {   key: string;   value: any;   editable: boolean;   objectType?: "ref" | "reactive" | "computed" | "other";   raw?: string;   type?: string; } useDevtoolsComponentState([   {     key: "_bar",     type: "direct",     value: "bar",     editable: true   },   {     key: "_baz",     type: "direct",     value: "baz",     editable: false   } ]);
// raw change useDevtoolsComponentState((payload, ctx) => {   payload.state.push(     ...[       {         key: "_bar",         type: "raw",         value: "bar",         editable: true       },       {         key: "_baz",         type: "raw",         value: "baz",         editable: false       }     ]   ); });

Timeline events

To add timeline events:

const id = "vue-composable";
const label = "Test events";
const color = 0x92a2bf;
const { addEvent, pushEvent } = useDevtoolsTimelineLayer(   id,   description,   color );
// adds event to a specific point in the timeline addEvent({   time: Date.now(),   data: {     // data object   },   meta: {     // meta object   } });
// adds event with time: Date.now() pushEvent({   data: {     // data object   },   meta: {     // meta object   } });

Inspector

Allows to create a new inspector for your data.

I'm still experimenting on how to expose this API on a composable, this will likely to change in the future, suggestions are welcome.

useDevtoolsInspector(
  {
    id: "vue-composable",
    label: "test vue-composable"
  },
  // list of nodes, this can be reactive
  [
    {
      id: "test",
      label: "test - vue-composable",
      depth: 0,
      state: {
        composable: [
          {
            editable: false,
            key: "count",
            objectType: "Ref",
            type: "setup",
            value: myRefValue
          }
        ]
      }
    }
  ]
);

Typescript

Typescript@3.x is not supported, the supported version can be checked on package.json, usually is the latest version or the same major as vue-3

Contributing

You can contribute raising issues and by helping out with code.

Tests and Documentation are the most important things for me, because good documentation is really useful!

I really appreciate some tweaks or changes on how the documentation is displayed and how to make it easier to read.

Twitter: @pikax_dev

Build

# install packages
yarn
build and test for v2
yarn build --version=2
yarn test:vue2
build and test for v3
yarn build
yarn test

New composable

• Fork it!
• Create your feature branch: git checkout -b feat/new-composable
• Commit your changes: git commit -am 'feat(composable): add a new composable'
• Push to the branch: git push origin feat/new-composable
• Submit a pull request

License

MIT

[now]: https://pikax.me/vue-composable/composable/date/now [date-now]: https://pikax.me/vue-composable/composable/date/dateNow [performance-now]: https://pikax.me/vue-composable/composable/date/performanceNow [pagination]: https://pikax.me/vue-composable/composable/pagination/pagination [array-pagination]: https://pikax.me/vue-composable/composable/pagination/arrayPagination [promise]: https://pikax.me/vue-composable/composable/promise/promise [retry]: https://pikax.me/vue-composable/composable/promise/retry [cancellable-promise]: https://pikax.me/vue-composable/composable/promise/cancellablePromise [debounce]: https://github.com/pikax/vue-composable