anyword API reference

anyword is a micro text segmenter built entirely on the native Intl.Segmenter API. Four functions, one options object, three granularities. Stable since 1.0 — the public API follows semver.

Naive JS quietly gets text wrong: .length miscounts emoji and accents, .split(" ") finds no words in Chinese or Thai, [...str] rips 👨‍👩‍👧‍👦 into pieces. The browser already knows where the real boundaries are. anyword is the thin wrapper — no rule tables, no locale files, no config.

import { anyword, anyword.count, anyword.truncate } from 'anyword'

anyword("don't stop 世界")
// ["don't", "stop", "世界"]

anyword("👨‍👩‍👧 hi", { by: 'grapheme' })
// ["👨‍👩‍👧", " ", "h", "i"]

anyword.count("世界 test")
// 2

anyword.truncate("héllo 👨‍👩‍👧", 5, { ellipsis: '…' })
// "héllo…"   — never cuts an emoji in half

npm install anyword
# or
pnpm add anyword
# or
yarn add anyword

Zero dependencies, under 1kb gzipped, ESM and CJS builds with types. Also on JSR. Or take the whole family at once with npm install anyfamily.

The main entry point. Pass text, optionally pass options. Returns the segments as plain strings, in order.

anyword(text)
anyword(text, options?)

anyword('hi there')                      // ["hi", "there"]
anyword('hi there', { by: 'grapheme' })  // ["h","i"," ","t","h","e","r","e"]
anyword("don't stop 世界")                // ["don't", "stop", "世界"]
anyword('Hi. Go now!', { by: 'sentence' })  // ["Hi. ", "Go now!"]

Word mode drops the segments between words — spaces and punctuation. Set raw: true to keep them, and the pieces join back into the original string.

anyword('hi, there!')                  // ["hi", "there"]
anyword('hi, there!', { raw: true })   // ["hi", ",", " ", "there", "!"]

2.0 removed the separate anywordPartsand the other extra exports — they are the same functions and values, reached through the one name the package exports.

- import { anyword, anywordCount, anywordTruncate, supported } from 'anyword'
+ import { anyword } from 'anyword'

- anywordCount(text)
+ anyword.count(text)

- anywordTruncate(text, 20)
+ anyword.truncate(text, 20)

- supported ? anyword(text) : text.split(/\s+/)
+ anyword.supported ? anyword(text) : text.split(/\s+/)

Arguments, return values and throwing behaviour are unchanged, and nothing else in the API moved. Every any* package follows this shape from 2.0 on: the bare call does the job, everything else hangs off the same name.

Same arguments as anyword(), but returns { segment, index, isWordLike? } instead of plain strings. The offsets point into the original text, so you can highlight or slice without searching again.

import { anyword } from 'anyword'

anyword.parts('世界 test')
// [
//   { segment: '世界', index: 0, isWordLike: true },
//   { segment: 'test', index: 3, isWordLike: true },
// ]

// React: highlight the matched word in place
anyword.parts(text, { raw: true }).map((p, i) =>
  p.segment === query ? <mark key={i}>{p.segment}</mark> : p.segment,
)

isWordLike is present in word mode only — in grapheme and sentence modes every segment is content.

Takes the same options and counts segments instead of returning them.

anyword.count('世界 test')                  // 2
anyword.count('世界test')                   // 2   — .split(/\s+/) says 1
anyword.count('héllo', { by: 'grapheme' })  // 5
anyword.count('👨‍👩‍👧', { by: 'grapheme' })    // 1   — "👨‍👩‍👧".length is 8

Grapheme counting is what a char-limit counter should show: the number of characters the user believes they typed.

anyword.truncate(text, limit, options?) cuts to at most limit segments — graphemes by default, so an emoji or an accented letter is never split.

anyword.truncate('héllo 👨‍👩‍👧', 6)                     // "héllo "
anyword.truncate('héllo 👨‍👩‍👧', 5, { ellipsis: '…' })   // "héllo…"
anyword.truncate('one two three', 2, { by: 'word' })  // "one two "
anyword.truncate('short', 99)                         // "short"  — already fits

The cut lands on a segment boundary and keeps everything before it verbatim, trailing whitespace included. With ellipsis, that whitespace is trimmed and the ellipsis appended — and only when the text was actually too long, so short input comes back untouched. The ellipsis itself does not count toward limit.

Throws RangeError if limit is negative or not finite.

by maps straight to Intl.Segmenter.

Grapheme and sentence modes never drop anything, so raw does nothing there.

Every one of these is a bug report waiting to be filed by a user with an emoji in their name.

Copy, paste, move on.

// Word counter
anyword.count(post.body)
// 412

// Character counter users agree with (👨‍👩‍👧 counts as 1, not 8)
anyword.count(input, { by: 'grapheme' })

// Safe preview / char-limit cut
anyword.truncate(bio, 140, { ellipsis: '…' })

// Word-limited excerpt
anyword.truncate(article, 30, { by: 'word', ellipsis: ' …' })

// Per-character animation, emoji intact
anyword(title, { by: 'grapheme' }).map((c, i) => <span key={i}>{c}</span>)

// Safe reverse
anyword(text, { by: 'grapheme' }).reverse().join('')

// Initials
anyword(fullName).slice(0, 2)
  .map((w) => anyword(w, { by: 'grapheme' })[0])
  .join('')

// Split into sentences
anyword(text, { by: 'sentence' })

anyword is pure and synchronous, so it works in a component as-is. Whatanyfamily-react adds is a shared locale: set it once onAnyfamilyProvider and every hook below picks it up, so you do not thread locale through every call.

import { AnyfamilyProvider, useAnyword, useAnywordCount } from 'anyfamily-react'

function CharCounter({ value }: { value: string }) {
  return <span>{useAnywordCount(value, { by: 'grapheme' })}/280</span>
}

// useAnyword returns an array, so it is memoized — the same segments keep the
// same reference until the text or the options change.
function Letters({ title }: { title: string }) {
  return useAnyword(title, { by: 'grapheme' }).map((c, i) => <span key={i}>{c}</span>)
}

`anywordSupported` is re-exported for feature-detecting `Intl.Segmenter`.

anyword is pure and synchronous — no clock, no state — so it renders the same on server and client. Pass a locale to keep output stable across the hydration boundary regardless of the runtime default.

import { anyword } from 'anyword'

export function CharCounter({ value }: { value: string }) {
  return (
    <span>{anyword.count(value, { by: 'grapheme', locale: 'en' })}/280</span>
  )
}

Pass any valid BCP 47 tag. Fallback arrays also work. The locale matters most for word breaking in scripts without spaces.

anyword('これは日本語です', { locale: 'ja' })  // ["これ", "は", "日本語", "です"]
anyword('สวัสดีชาวโลก', { locale: 'th' })   // ["สวัสดี", "ชาว", "โลก"] — no spaces needed
anyword("don't stop", { locale: 'en' })     // ["don't", "stop"]
anyword('hi', { locale: ['xx-Nope', 'en'] })

When omitted, native Intl uses the runtime locale.

Intl.Segmenter is missing on older runtimes. There anyword throws a clear error at call time; check the exported supported flag first if you target them.

import { anyword } from 'anyword'

anyword.supported ? anyword(text) : text.split(/\s+/)

Through the anyfamily meta-package the same flag is exported as anywordSupported, since supportedcollides with anylong's.

What you would otherwise reach for, and what changes if you do.

anyword is not an NLP toolkit — it does one thing. Reach for a tokenizer or a full i18n framework when you need stemming, stop words or message catalogs.

anyword uses Intl.Segmenter — supported everywhere modern, and detectable via supported where it is not.

A few things worth knowing before you ship: