pikax
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-composableDocumentation
Check our documentation
Composable
Event
- Event - Attach event listener to a DOM element
- Mouse Move - Attach
mousemovelistener to a DOM element - Resize - Attach
resizelistener to a DOM element - Scroll - Attach
scrolllistener 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
Breakpoint
- MatchMedia - reactive
MatchMedia - Breakpoint - reactive
breakpointsbased onwindow.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
setIntervalon unmount - lockScroll -
lock-scrollcomponent - refDebounced - debounces the update value of a
ref
Storage
- WebStorage - Reactive access to
Storage API,useLocalStorageanduseSessionStorageuse this - storage - uses
localStorageor on safari private it usessessionStorage - 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
Intl
- dateTimeFormat - Intl.DateTimeFormat
- numberFormat - Intl.NumberFormat
- currencyFormat - CurrencyFormat with Intl.NumberFormat
Promise
- Promise -
Promisereactive 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
undoandredo - valueSync - syncs variables value, across multiple
refs
Web
- Fetch - reactive
fetchwrapper - WebSocket - reactive
WebSocketwrapper - IntersectionObserver - reactive
IntersectionObserver - NetworkInformation - reactive
NetworkInformationwrapper - Online - reactive
navigator.onLinewrapper - 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
axioswrapper client - makeAxios - @vue-composable/axios wrap your
axiosinstance - useCookie - @vue-composable/cookie
js-cookiewrapper
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.
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.xis not supported, the supported version can be checked on [package.json](./package.json), usually is the latest version or the same major asvue-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 testNew 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