vue-balloon
Vue.js plugin to create a floating element that expands when clicked.
Check out the example here.
Dependencies
This plugin uses font awesome icons so either include that or redefine custom icons for the classes .fa-chevron-up, .fa-chevron-down, .fa-expand, .fa-compress, .fa-close.
Install & Basic Usage
Add as dependency with npm or yarn.
npm install vue-balloon --save
or
yarn add vue-balloon
<template>
<div id = 'demo'>
<balloon
title = 'One Cute Cat'
position = 'bottom-right'
@maximize = 'playVideo'
@minimize = 'pauseVideo'
>
<!-- balloon content goes here.. for example a youtube video with the vue-youtube-embed plugin -->
<youtube video-id = '0Bmhjf0rKe8' ref = 'player'>
</youtube>
</balloon>
</div>
</template>
<script>
import { Balloon } from 'vue-balloon'
export default {
components: { Balloon },
methods: {
playVideo () {
this.$refs.player.player.playVideo()
},
pauseVideo () {
this.$refs.player.player.pauseVideo()
}
}
}
</script>Multiple Balloons
To achieve multiple fixed balloons on the same page we use Vue's scoped slot functionality paired with the vue-balloon BalloonSet component.
<template>
<div id = 'demo'>
<balloon-set
position = 'bottom-right'
:balloons = 'balloons'
>
<template scope = 'balloon'>
<!--
The multi balloon content goes here, scoped by the 'balloon' variable.
In this example we will extract the videoId attribute from each
balloon object to use in the video props
-->
<youtube :video-id = 'balloon.videoId' class = 'video'>
</youtube>
</template>
</balloon-set>
</div>
</template>
<script>
import { BalloonSet } from 'vue-balloon'
export default {
components: {
BalloonSet
},
data () {
return {
balloons: [
// Each balloon object can contain any props used in the balloon
// component (other than the position prop that should be set on the
// BalloonSet component instead). Events will also be propagated to
// the balloon component from the nested 'on' object.
{
key: 1,
videoId: '0Bmhjf0rKe8',
title: 'One Cute Cat',
on: {
maximize (balloonRef) { console.log('maximized', balloonRef) },
minimize (balloonRef) { console.log('minimized', balloonRef) }
}
},
{ key: 2, videoId: '28xjtYY3V3Q', title: 'And Some Cute Dogs!' }
]
}
}
}
</script>Caveats and Gotchas
For multiple balloons with the BalloonSet component:
- Whenever a balloon is
maximizedto take up most of the window it will re-render the slot contents from scratch. - If you need to have reactive data inside each balloon it is recommended to store it inside of a nested balloon object. Otherwise the attributes are considered slot props and cannot be modified. For example:
<template>
<div id = 'demo'>
<balloon-set
position = 'bottom-right'
:balloons = 'balloons'
>
<template scope = 'balloon'>
<!--
Some balloon with form content
-->
Name: <input v-model = 'balloon.data.name'/>
</template>
</balloon-set>
</div>
</template>
<script>
import { BalloonSet } from 'vue-balloon'
export default {
components: {
BalloonSet
},
data () {
return {
balloons: [
{
key: 1,
title: 'Edit Username',
data: {
name: 'Amelia Pond'
}
},
{
key: 2,
title: 'Edit Username',
data: {
name: 'Rory Williams'
}
}
]
}
}
}
</script>
Component: Balloon
methods
These methods are exposed by the balloon component if needed:
methods: {
// closes the balloon as if hitting the X button
// note: closing the balloon merely sets the close data
// attribute and does not remove the component itself or
// remove it from the balloons array
close () {}
// reopen the balloon (reverse of close)
open () {},
// maximizes the balloon (full window)
maximize () {
this.balloonState.maximized = this.balloon
},
// minimizes the balloon (reverse of maximize)
minimize () {
this.balloonState.maximized = null
}
}
events
These events are emitted from the balloon component.
-
v-on:close: when the balloon is closed -
v-on:open: when the balloon is opened -
v-on:maximize: when the balloon is maximized -
v-on:minimize: when the balloon is minimized
props
props: {
// balloon title
title: {
default: '',
type: String
},
// position: bottom-right, bottom-left, top-right, or top-left
position: {
default: 'bottom-right',
type: String
},
// enable the css transform: scale() effect
zooming: {
default: false,
type: Boolean
},
// hide the close (x) icon on the balloon
hideCloseButton: {
default: false,
type: Boolean
},
// hide the concise (chevron) icons on the balloon
hideConciseButton: {
default: false,
type: Boolean
},
// when balloon is created it will have this initial 'concise' state
initiallyConcise: {
default: false,
type: Boolean
},
// when balloon is maximized, it will still have the close button
showCloseWhenMaximized: {
default: false,
type: Boolean
}
}
Component: BalloonSet
BalloonSet was added in vue-balloon v1.0.18
props
props: {
// position: bottom-right, bottom-left, top-right, or top-left
// (overrides the Balloon component position)
position: {
default: 'bottom-right',
type: String
},
// Balloon component data objects array, each object can contain props
// that propagate to their own Balloon component
balloons: {
default: [],
type: Array
},
// keep the minimized ballon when the corresponding balloon is maximized
dockKeepMaximized: {
default: false,
type: Boolean
},
// keep the balloon dock in front of the mask when a balloon is maximized
dockBringToFront: {
default: false,
type: Boolean
}
}Contributing
# install dependencies
npm install
# serve with hot reload at localhost:8080
npm run dev
# build for production with minification
npm run build
# build demo (used to prepare for gitlab pages)
npm run build:demo
# run unit tests
npm run unit
# run e2e tests
npm run e2e
# run all tests
npm test
