# wrInitials

> Up to two initials of a name, one grapheme each. What `wr-avatar` draws for its `name`.

Source: https://ngwr.dev/reference/utils/wr-initials  
Kind: Util  
Added in v15.6  
Optional

## Usage

The first two words give one initial each. A one-word name gives one. Punctuation, extra whitespace, `null` and `undefined` never throw.

```typescript
import { wrInitials } from 'ngwr/utils';

wrInitials('Roman Khegay');        // 'RK'
wrInitials('  ada   lovelace  ');  // 'AL'
wrInitials('Ada King Lovelace');   // 'AK'
wrInitials('Jean-Luc Picard');     // 'JP'
wrInitials('Madonna');             // 'M'
wrInitials(null);                  // ''
```

## Scripts

A grapheme is what a reader sees as one character, so an emoji, a letter with marks or a surrogate pair is one initial, never half of one.

```typescript
wrInitials('👩🏽‍🚀 Valentina');   // '👩🏽‍🚀V', one grapheme each
wrInitials('émile zola');         // 'ÉZ'
wrInitials('ßen müller');         // 'ßM', an upper case of two letters is kept as written
wrInitials('王小明');              // '王', one character for Han, Hangul and kana
wrInitials('محمد علي');           // 'مع'
wrInitials('ismail', 'tr');       // 'İ', the locale's mapping
```

## Rules

| Input | Result |
| --- | --- |
| Three or more words | The first two: `Ada King Lovelace` gives `AK`. |
| One word | One initial: `Madonna` gives `M`. |
| A hyphen | Inside a word: `Jean-Luc Picard` gives `JP`. |
| Punctuation first | Skipped: `(Ada)` gives `A`. A word of punctuation alone yields nothing. |
| Digits | Count: `Agent 007` gives `A0`. |
| Han, Hangul, kana | One character, the first: `王小明` gives `王`, `김 철수` gives `김`. |
| Upper case | The default mapping, or the `locale` given. A letter whose upper case is two (`ß`) is kept as written. |
| Empty, blank, `null` | `''` |

## API

| Name | Description | Type | Default |
| --- | --- | --- | --- |
| `wrInitials(name, locale?)` | Up to two initials, one grapheme each, upper-cased. A word is a run between whitespace; its initial is its first letter, digit or emoji. `locale` picks the upper-case mapping; without it the default mapping, the same on the server and the client. | `(name: string \| null \| undefined, locale?: string) => string` | `-` |

## See also

- [wrInitials](https://ngwr.dev/reference/pipes/wr-initials) — Up to two initials of a name, one grapheme each.
- [Avatar](https://ngwr.dev/reference/components/avatar) — A user's picture, with initials as the fallback.
- [wrTruncate](https://ngwr.dev/reference/pipes/wr-truncate) — Shorten a string and end it with an ellipsis.