Split Text into Lines, Words, or Characters – Split Text

Are you looking to gain granular control over the text in your HTML elements?

Split Text is a small JavaScript library designed for just that. It allows you to break down text within HTML elements into individual lines, words, or characters for advanced text control and effects.

Features:

• Fine-grained Text Animation: By splitting text into individual elements, you can animate lines, words, or characters independently. This opens up creative text animation possibilities for engaging user experiences.
• Responsive Typography: Control text layout at a deeper level to ensure readability and visual harmony across different screen sizes. Splitting text allows for adjustments and manipulations that standard CSS alone cannot achieve easily.
• Enhanced User Interaction: Create interactive text effects where individual words or characters respond to user actions like hover or click, adding a layer of dynamic engagement to your website.
• CJT Language Support: Split Text handles complexities of Chinese, Japanese, Korean, and Thai (CJT) languages. It also supports emojis and nested HTML elements.
• Text Balancing for Visual Appeal: The library incorporates text balancing, powered by balance-text, to improve the visual rhythm of your text blocks, especially in headlines or short paragraphs. This feature helps create a more polished and professional look.
• Accessibility Considerations: Split Text includes accessibility features by providing options to manage ARIA labels.

How to use it:

1. Install the library via npm and then import it into your project:

# NPM
$ npm install @activetheory/split-text

import SplitText from '@activetheory/split-text';

2. Initialize Split Text on the HTML element containing the text you want to split. This basic setup, by default, will split your text into lines.

<div class="el">
  Your Text Here
</div>

const el = document.querySelector('.el');
const instance = new SplitText(el);

3. Customize Split Text with these options during initialization:

• type: Determines how the text is split. Choose from ‘lines’, ‘words’, or ‘chars’.
• minLines: Sets the minimum number of lines after splitting. Useful for ensuring a certain text layout.
• lineThreshold: A number between 0 and 1 that dictates the sensitivity for line breaking. Adjust this value (e.g., 0.1 or 0.3) if line splitting is not behaving as expected.
• noAriaLabel: A boolean value. If set to true, it prevents the library from adding .sr-only screen reader content, giving you control over accessibility attributes.
• noBalance: A boolean value. If set to true, disables text balancing.
• balanceRatio: A number that adjusts the text balancing behavior.
• handleCJT: A boolean value. When set to true, it activates special handling for CJT characters. You might need to manually insert ​ in your text for optimal CJT splitting.

const instance = new SplitText(el,{
  lineThreshold: 0.2,
  type: 'lines',
  noAriaLabel: false,
  noBalance: false,
  balanceRatio: 1,
  minLines: 1,
  handleCJT: false,
});

4. After initializing SplitText, you can access these properties of the instance:

// A boolean indicating if the text has been split successfully (true) or not (false).
nstance.isSplit
// An array containing all character elements if you split by characters.
instance.chars
// An array containing all word elements if you split by words or lines.
instance.words
// An array containing all line elements if you split by lines.
instance.lines
// An array storing the original HTML content of the split elements before modification.
instance.originals.

5. Control the text splitting process using these methods:

// Manually trigger the text splitting process. 
// This is automatically called during instance creation, but you can call it again if needed.
instance.split()
// Restores the HTML content of the element back to its original state before splitting. 
// This is useful for undoing the split effect or for re-splitting with different options.
instance.revert()

FAQs:

Q: Will the text splitting affect SEO?
A: No, the library maintains the original text structure and adds ARIA labels for accessibility, preserving SEO-friendly content.

Q: Can I animate the split elements?
A: Yes, each split element receives a class name (line, word, or char) that you can target with CSS animations.

Q: Does it work with dynamic content?
A: Yes, you can rerun the split operation when content changes using the split() and revert() methods.