Vue 3 Splitting

Part of southcoastweb's contribution to Free and Open Source Software (FOSS)

To read more about southcoastweb and our open-source software, go to our Open-Source page.

VersionLicenseMonthly DownloadsMonthly Downloads

Vue3 Splitting is a lightweight, Vue-centric version of Stephen Shaw’s and Christopher Wallis’ excellent JavaScript library Splitting. While Vue components are primarily data-driven, Splitting operated by manipulating the DOM directly. While there were alternatives (the html() function), these came with their own shortcomings in terms of support for Server-Side Rendering.

We also needed a few extra options when building the southcoastweb site, namely the ability to independently control the enabling of char, word and line splitting and to offset the counts (allowing us to create multiple split blocks of text with consecutive counts). Since there didn’t seem to be an obvious Vue3 answer, we made one ourselves.


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";
4const { Splitting, counts } = useSplitting('Hello World!', {
5 // ... config goes here

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:

<Splitting />

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

linesbooleanSplit text by lines (<br> or \n)true
wordsbooleanSplit text by words (whitespace)true
charsbooleanSplit text by characterstrue
lineOffsetnumberStart counting lines at x0
wordOffsetnumberStart counting words at x0
charOffsetnumberStart counting characters at x0
wrapperTagkeyof HTMLElementTagNameMapRender the wrapping HTML element as xdiv
lineTagkeyof HTMLElementTagNameMapRender each line HTML element as xdiv
lineClassstringAdd this class string to every line element<empty>
wordTagkeyof HTMLElementTagNameMapRender each word HTML element as xspan
wordClassstringAdd this class string to every word element<empty>
charTagkeyof HTMLElementTagNameMapRender each character HTML element as xspan
charClassstringAdd this class string to every character element<empty>

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"

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.

import { Vue3Splitting } from 'vue3-splitting';
export default {
components: {
<Vue3Splitting class="my-4" wrapper-tag="ul" line-tag="li" :words="false">Hello World!</Vue3Splitting>

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.

Copyright 2007 - 2024 southcoastweb is a brand of DSM Design.