A React component for finding matches within a split string.
npm install split-matchA React component for finding matches within a split string
- Introduction
- Installation & Usage
- API
- Contributing
- Release Checklist
- License
SplitMatch splits a supplied string into separate React elements. Yeah, no big deal! But in addition, it also wraps any text that matches the supplied search text in a React element, even when the matched text is divided across the elements created by the split. If this makes no sense, read on...
SplitMatch is particularly useful for building components like an autocomplete, where the text entered is highlighted in the accompanying listbox options:
!Entering text into an autocomplete control
The markup for the example above is simple. Each listbox option looks something like this, with the element denoting the matched search text:
``html`
Converting this into a React component would be straightforward.
However, what if we wanted to pretty things up a little and apply some formatting to our listbox options? We may want the state and country names to appear in a smaller font than the city name, like in this SplitMatch example:
!Entering text into an autocomplete control with formatted results
Here we may need to take a string such as "Springfield, Michigan, United States" and split it at the first comma so we can apply different styling to each element. For example:
`html`
Springfield,
Michigan, United States
Things get complicated when we add the text matching back, because the matched text may span across more than one of the splits. An example in this case would be a search for "Springfield, Mi". Given all the Springfields in the United States (incidentally it's 34)!), the likelihood is you'd need to type past the comma to find your match. This would require listbox markup such as this:
`html`
Springfield,
Michigan, United States
Here's where the SplitMatch component comes in handy. It takes a string, a separator character and some search text and converts it into customisable React Elements with markup such as the example above.
This allows lots of flexibility in formatting and at the same time allows matched text to be easily displayed, even when it is split between different block elements. Note that in this example, you can also choose whether to hide the delimiter/separator character, in this case the first comma in the top listbox option.
!Entering text into an autocomplete control with formatted results
`bash`
$ npm install split-match
#### Basic Example:
`jsx
import React from 'react'
import SplitMatch from 'split-match'
export default ListboxOption = () => {
return (
This would produce the following markup inside the
element:`html
New York City,
New York,
United States
`#### Full Example:
jsx
import React from 'react'
import SplitMatch from 'split-match'const SplitComponent = (props) => {
const { children, index } = props
return
split${index}}>{children}
}const MatchComponent = (props) => {
const { children } = props
return {children}
}
export default ListboxOption = () => {
return (
caseSensitiveSplit={false}
globalMatch={false}
globalSplit={false}
includeSeparator={false}
searchText={'new york city, new'}
separator=","
MatchComponent={MatchComponent}
SplitComponent={SplitComponent}>
New York City, New York, United States
)
}
`This would produce the following markup inside the
element:`html
New York City
New York, United States
`$3
The following props can be supplied to the
component:####
caseSensitiveMatch
- Type:
- Default:
- If the searchText value is matched with case sensitivity applied.####
caseSensitiveSplit
- Type:
- Default:
- If the separator character is searched for with case sensitivity applied.####
globalMatch
- Type:
- Default:
- If every instance of searchText is matched in the supplied string.
- If false only the first instance of searchText is matched in the supplied string.####
globalSplit
- Type:
- Default:
- If the supplied string is split at every instance of separator.
- If false the supplied string is split only at the first instance of separator.####
includeSeparator
- Type:
- Default:
- Whether or not to include or remove the character(s) within the supplied string.
- If true the separator remains in the supplied string.
- If false the separator is removed from supplied string. If globalSplit is also true, all instances of separator are removed. If globalSplit is false, only the first instance of separator is removed.####
searchText
- Type:
- Default:
- This text is matched within the larger string.
- Use to determine whether to match every instance of searchText in the string, or just the first instance. If the search text is case sensitive, specifiy using caseSensitiveMatch.####
separator
- Type:
- Default:
- It is recommended that this be a single character delimiter, by which to split the supplied string. Use to determine whether to split at every instance of separator or just the first instance. If the separator is case sensitive, specifiy using caseSensitiveSplit.The following components can be supplied to the
component as props:####
MatchComponent
- Type: React Component
- Default:
- This component is passed the following props:
- - The matched text string
- This is a customisable wrapper element (or elements) for the matched text####
SplitComponent
- Type: React Component
- Default:
- This component is passed the following props:
- (string) - The matched text string
- index (number) - The index of the split text (starts at 0)
- This is a customisable wrapper element (or elements) for the split textContributing
- Fork the project
- Run the project in development mode: $ npm run dev
- Make changes.
- Add appropriate tests
- (or $ npm run watch)
- Ensure all tests pass and any snapshot changes are fully reviewed
- Update README with appropriate docs.
- Commit and PRRelease checklist
- Update CHANGELOG
- Update version number in package.json
- $ git tag vN.N.N
- Push tag
-
- MIT