split-match

SplitMatch React Component

A React component for finding matches within a split string

• Introduction
• Installation & Usage
• API
• Contributing
• Release Checklist
• License

Introduction

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...

Why would I need this?

SplitMatch is particularly useful for building components like an autocomplete, where the text entered is highlighted in the accompanying listbox options:

The markup for the example above is simple. Each listbox option looks something like this, with the <strong> element denoting the matched search text:

<li><strong>New Yor</strong>k City, New York, United States</li>

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:

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:

<li>
  <span class="split1">Springfield,</span>
  <span class="split2"> Michigan, United States</span>
</li>

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:

<li>
  <span class="split1"><strong>Springfield,</strong></span>
  <span class="split2"><strong> Mi</strong>chigan, United States</span>
</li>

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.

Installation & Usage

Installing

$ npm install split-match

Usage

Basic Example:

import React from 'react'
import SplitMatch from 'split-match'

export default ListboxOption = () => {
  return (
    <li>
      <SplitMatch searchText={'New York City, New'} separator=",">
        New York City, New York, United States
      </SplitMatch>
    </li>
  )
}

This would produce the following markup inside the <li> element:

<span><strong>New York City,</strong></span>
<span><strong> New</strong> York,</span>
<span> United States</span>

Full Example:

import React from 'react'
import SplitMatch from 'split-match'

const SplitComponent = (props) => {
  const { children, index } = props
  return <div className={`split${index}`}>{children}</div>
}

const MatchComponent = (props) => {
  const { children } = props
  return <span className={'match'}>{children}</span>
}

export default ListboxOption = () => {
  return (
    <li>
      <SplitMatch
        caseSensitiveMatch={false}
        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
      </SplitMatch>
    </li>
  )
}

This would produce the following markup inside the <li> element:

<div class="split0"><span class="match">New York City</span></div>
<div class="split1"><span class="match"> New</span> York, United States</div>

API

The following props can be supplied to the <SplitMatch> component:

caseSensitiveMatch

• Type: boolean
• Default: false
• If true the searchText value is matched with case sensitivity applied.

caseSensitiveSplit

• Type: boolean
• Default: false
• If true the separator character is searched for with case sensitivity applied.

globalMatch

• Type: boolean
• Default: true
• If true 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: boolean
• Default: true
• If true 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: boolean
• Default: true
• Whether or not to include or remove the separator 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: string
• Default: ''
• This text is matched within the larger string.
• Use globalMatch 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: string
• Default: ','
• It is recommended that this be a single character delimiter, by which to split the supplied string. Use globalSplit 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 <SplitMatch> component as props:

MatchComponent

• Type: React Component
• Default: undefined
• This component is passed the following props:
  • children - The matched text string
• This is a customisable wrapper element (or elements) for the matched text

SplitComponent

• Type: React Component
• Default: undefined
• This component is passed the following props:
  • children (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 text

Contributing

• Fork the project
• Run the project in development mode: $ npm run dev
• Make changes.
• Add appropriate tests
• $ npm test (or $ npm run watch)
• Ensure all tests pass and any snapshot changes are fully reviewed
• Update README with appropriate docs.
• Commit and PR

Release checklist

• Update CHANGELOG
• Update version number in package.json
• $ git tag vN.N.N
• Push tag $ git push --tags
• $ npm run build
• $ npm publish

License

MIT