v-breakpoints is a Vue 3 plugin designed to streamline responsive design by providing a centralized way to manage and listen to viewport changes. It simplifies handling breakpoints and screen sizes, enhancing component behavior and layout adjustments across various devices.
First, install the package via npm:
npm install v-breakpointsOr viw yarn:
yarn add v-breakpointsTo utilize v-breakpoints, install the plugin in your main.js or main.ts file. This step is mandatory for the plugin to function correctly.
import { createApp } from 'vue';
import App from './App.vue';
import { breakpoints } from 'v-breakpoints';
const app = createApp(App);
app.use(breakpoints);
app.mount('#app');The useBreakpoints hook is central to this plugin. Initially, it returns the reactive states breakpoint and screen.
Check here breakpoint and screen values
import { useBreakpoints } from 'v-breakpoints';
export default {
setup() {
const { breakpoint, screen } = useBreakpoints();
return {
breakpoint,
screen,
};
},
};To leverage the full suite of reactive states provided by useBreakpoints, import and use the hook as shown below.
import { useBreakpoints } from 'v-breakpoints';
export default {
setup() {
const {
breakpoint,
screen,
width,
height,
breakpointWidth,
screenWidth,
orientation,
is,
event,
breakpoints,
screens
} = useBreakpoints();
return {
breakpoint,
screen,
width,
height,
breakpointWidth,
screenWidth,
orientation,
is,
event,
breakpoints,
screens
};
},
};| Property | Description |
|---|---|
| breakpoint | Current breakpoint as per defined here |
| screen | Current screen as per defined here |
| width | Current viewport width. |
| height | Current viewport height. |
| breakpointWidth | Width corresponding to the current breakpoint. |
| screenWidth | Width corresponding to the current screen size. |
| orientation | Current screen orientation (portrait, landscape or square). |
| event | Last resize event data. |
| breakpoints | Object containing all defined breakpoints. |
| screens | Object containing all defined screens. |
| is | Utility to check if the current breakpoint or screen matches a specific size. |
The is object provides a boolean map indicating which breakpoint or screen matches the current viewport.
if (is.xs) {
console.log("Current breakpoint is extra small");
}
if (is.lg) {
console.log("Current breakpoint is large");
}
if (is.phone) {
console.log("Current screen size is a phone");
}
if (is.lg && is.tablet) {
console.log("Current breakpoint is large and screen is tablet");
}You can listen to custom events for changes in breakpoints, screens, or orientation.
import { EventPayload } from 'v-breakpoints';
onMounted(() => {
window.addEventListener("breakpoint:change", handleChange);
window.addEventListener("screen:change", handleChange);
window.addEventListener("orientation:change", handleChange);
})
function handleChange(event: EventPayload) {
console.log("Event Payload:", event.payload);
}The event.payload includes detailed information about the current viewport state:
-
breakpoint: The active
breakpoint. -
breakpointWidth: Width of the current
breakpoint. -
screen: Active
screensize category. -
screenWidth: Width of the current
screen. -
orientation: Current
orientation. - width: Current viewport width.
- height: Current viewport height.
v-breakpoints provides directives to directly react to viewport changes in your templates.
-
v-breakpoint-change: Reacts to
breakpointchanges. -
v-screen-change: Reacts to
screenchanges. -
v-orientation-change: Reacts to
orientationchanges
<template>
<div v-orientation-change="handleOrientationChange">
<!-- Content goes here -->
</div>
</template>
<script lang="ts">
import { EventPayload } from 'v-breakpoints';
export default {
setup() {
const handleOrientationChange = (event: EventPayload) => {
console.log("Orientation changed to:", event.payload?.orientation);
};
return {
handleOrientationChange,
};
},
};
</script>You can override the default breakpoints and screens by passing options during plugin installation. This flexibility allows you to tailor the plugin to fit your specific design requirements.
import { createApp } from 'vue';
import App from './App.vue';
import { breakpoints } from 'v-breakpoints';
createApp(App)
.use(breakpoints, {
screens: {
"mini-tablet": 600,
},
breakpoints: {
md: 740,
"3xl": 1850,
},
})
.mount("#app");You can also define your own breakpoints and screens as shown below, which will override the default sizes defined by v-breakpoints.
import { createApp } from 'vue';
import App from './App.vue';
import { breakpoints } from 'v-breakpoints';
createApp(App)
.use(breakpoints, {
override: {
breakpoint: true, // Will not use `breakpoints` define by `v-breakpoints`
screen: true // Will not use `screens` define by `v-breakpoints`
},
screens: {
phone: 0, // 0px - 767px
tablet: 768, // 768px - 1600px
desktop: 1601, // 1601px - Above
},
breakpoints: {
xs: 0, // 0px - 767px
md: 768, // 768px - 1023px
lg: 1024, // 1024px - Above
},
})
.mount("#app");The default breakpoints follow Tailwind CSS standards.
const defaultBreakpoints = {
xs: 0, // 0px - 639px
sm: 640, // 640px - 767px
md: 768, // 768px - 1023px
lg: 1024, // 1024px - 1279px
xl: 1280, // 1280px - 1535px
"2xl": 1536, // 1536px - Above
};The default screens cover a range of typical device sizes.
const defaultScreens = {
phone: 0, // 0px - 767px
tablet: 768, // 768px - 1199px
laptop: 1200, // 1200px - 1600px
desktop: 1601, // 1601px - 1920px
largeDesktop: 1921 // 1921px - Above
};v-breakpoints is a robust solution for managing responsive design in Vue applications. By centralizing and simplifying viewport handling, it ensures consistent and maintainable responsive behavior across your application.
MIT License