Vue 3 Splitting

Installation

For those of you using NPM, you can install Vue3 Splitting like so:

npm i vue3-splitting

Or for the Yarn inclined:

yarn add vue3-splitting

While Vue3 Splitting itself doesn’t require installation, you can import the optional stylesheet which makes it easier to animate characters. Inside your Vue3 app:

import 'vue3-splitting/styles';

There are two ways of using Vue3 Splitting, the first is via a functional component which is geared towards those using the Composition API, the second is a standard Vue component which is for those using the Options API. We would recommend the former where possible.

Functional Component

1<script setup>
2import { useSplitting } from "vue3-splitting";
3
4const { Splitting, counts } = useSplitting('Hello World!', {
5	// ... config goes here
6});
7</script>

useSplitting is composable which returns a functional component (Splitting) and a reactive counts object. The counts object is a Vue reactive which looks like this:

/*
counts = {
	chars: 27,
	words: 4,
	lines: 1
}
*/

At the moment, using the functional component is the only way to get the counts data.

Then, using the functional component in your template is as simple as:

<template>
	<Splitting />
</template>

You can pass HTML attributes to the functional component which will fall through to the rendered HTML element, but config settings for the output itself should be passed as the second argument to your composable function. Here’s what you can pass:

Config Settings

Note that the configuration object passed as the second argument to useSplitting can be either a standard JavaScript object, or a Vue reactive object (ref, reactive, computed etc.). If you pass the latter, the output of the functional component will automatically update.

Functional Example

In our example, we’re going to use a ref for our string input and a standard JavaScript object for our configuration. We’ve also performed a rename on the functional component from Splitting to MySplittingElement. You’ll need to do this if you want to use more than one Splitting functional components in the same Vue component.

1const splittingString = ref('Hello World');
2const { Splitting: MySplittingElement } = useSplitting(splittingString, {
3	lineClass: 'my-splitting-element--line',
4	words: false,
5	wrapperTag: "h3"
6});

Standard Component

For those of you using the Options API, or who prefer to keep everything in the template, the standard component is a good alternative.

<script>
import { Vue3Splitting } from 'vue3-splitting';

export default {
	components: {
		Vue3Splitting
	}
};
</script>

<template>
	<Vue3Splitting class="my-4" wrapper-tag="ul" line-tag="li" :words="false">Hello World!</Vue3Splitting>
</template>

As you can see, on the standard component, the input string is passed through the default slot and both HTML attributes and config settings are passed as props on the component itself.

As with the input string for the composable, you’ll only be able to pass text, or a <br> tag inside the default slot of the Vue3Splitting component. Everything else will be ignored.

Feedback & Issues

If you come accross any issues in Vue3 Splitting, or have any suggestions as to how we can make it better, please use the discussion or issues tab on the Github repository respectively.

We’d also appreciate any stars you have spare on the repo.