Description:
Liseré is a lightweight and composable React component for text highlighting. It provides precise control over how users select, annotate, and interact with text.
The library gives you the tools to manage text selections effectively. You can define selection granularity, allow or disallow selections that span across multiple elements, and customize the appearance of highlights.
It also supports pre-loading existing highlights and provides callbacks for when text is selected, highlighted, or when a highlight is removed.
Features
- ✍️ Composable Component: Use the
<TextHighlighter />component to wrap any content you want to make highlightable. - 🎯 Precise Selection Control: Define selection granularity as either
'word'or'cursor'for fine-tuned user interaction. - 🎨 Custom Styling: Apply custom CSS classes and inline styles to highlighted text to match your application’s design.
- 🔗 Cross-Element Selection: Enable users to select and highlight text that spans across multiple HTML nodes.
- 💬 Custom Floating UI: Render a custom interface that appears when a user selects text, allowing for actions like confirming or canceling a highlight.
- 💾 Preloaded Highlights: Programmatically display existing highlights when the component first renders.
- 🔧 Utility Functions: Access a set of functions for manual control over highlighting, finding text, and removing highlights.
Preview
Use Cases
- Annotation Tools: Build a web application that allows students or researchers to highlight text in academic papers and add notes.
- Interactive Tutorials: Create engaging tutorials where users can highlight specific code snippets or key terms to reveal more information.
- Collaborative Editing: Develop a platform where multiple users can highlight and comment on a shared document in real-time.
- Digital Reading Apps: Implement a feature in an e-reader application for users to save and categorize their favorite passages from a book.
How to Use It
1. Install Liseré using your preferred package manager.
# npm
npm install lisere
# yarn
yarn add lisere
# pnpm
pnpm add lisere2. To enable text highlighting, wrap your content with the <TextHighlighter /> component. You can listen for new highlights using the onTextHighlighted callback.
import { TextHighlighter } from 'lisere';
function MyComponent() {
return (
<TextHighlighter
onTextHighlighted={selection => {
console.log('Text was highlighted:', selection.text);
}}
>
<p>Select any portion of this text to see it highlighted.</p>
</TextHighlighter>
);
}3. You can configure the component’s behavior through various props. For instance, you can change the highlight color, allow selections to cross paragraph boundaries, and let users remove highlights by clicking on them.
import { TextHighlighter } from 'lisere';
import type { CSSProperties } from 'react';
function AdvancedHighlighter() {
const highlightStyle: { className?: string; style?: CSSProperties } = {
style: { backgroundColor: '#aeeaaa', color: 'black' },
};
return (
<TextHighlighter
allowCrossElementSelection={true}
removeHighlightOnClick={true}
highlightStyle={highlightStyle}
>
<div>
<p>This component allows for advanced configuration.</p>
<p>You can select text across both of these paragraphs.</p>
<p>Click a highlight to remove it.</p>
</div>
</TextHighlighter>
);
}4. For more dynamic applications, you can use the useTextHighlighter hook to manage highlights programmatically. This is useful for features like search-term highlighting or clearing all highlights at once.
5. Here is a list of the props available for the <TextHighlighter /> component:
renderSelectionUI: A function that returns a React node to be displayed as a custom floating interface when text is selected.children: The content that you want to make highlightable.enabled: A boolean that determines if the highlighting functionality is active. It defaults totrue.containerElement: The HTML element to use as a wrapper for the content. The default is'div'.selectionBoundary: Defines the precision of the text selection. It can be set to either'word'or'cursor', with'word'as the default.highlightElement: The HTML tag used to wrap the highlighted text. The default is'span'.highlightStyle: An object containingclassNameandstyleproperties to apply custom styles to the highlights.allowCrossElementSelection: A boolean that, whentrue, permits users to select text that spans across multiple HTML elements. The default isfalse.clearSelectionAfterHighlight: A boolean that clears the browser’s native text selection after a highlight is created. This istrueby default.removeHighlightOnClick: A boolean that allows users to remove a highlight by clicking on it. It defaults tofalse.selectedContent: An array ofTextSelectionobjects to pre-load and display existing highlights.onTextSelected: A callback function that executes when a user selects text.onTextHighlighted: A callback function that is triggered after a highlight is officially created.onHighlightRemoved: A callback function that runs when a highlight is removed.
FAQs
Q: How can I style the highlighted text?
A: You can use the highlightStyle prop to pass a className for CSS stylesheets or a style object for inline styling.
Q: Is it possible to highlight text across different paragraphs or divs?
A: Yes, you can enable this by setting the allowCrossElementSelection prop to true.
Q: Can I save highlights and show them again later?
A: Yes. The onTextHighlighted callback provides the selection data which you can store. To display these highlights upon loading the component, pass the array of saved selections to the selectedContent prop.
Q: Can I create a custom popup menu that appears when text is selected?
A: You can use the renderSelectionUI prop. This prop accepts a function that returns a React node, which will be displayed as a floating UI when a user makes a text selection.
