Str::initials
Returns the first letter of each whitespace-separated word, optionally upper-cased.
Str::initials(string $value, bool $capitalize = false): stringParameters
| Parameter | Type | Description |
|---|---|---|
$$value | string | The string to reduce. It is split on runs of whitespace with mb_split, so every chunk contributes exactly one character. |
$$capitalizeoptional | bool= false | When true, the assembled initials are passed through Str::upper(). |
Return value
stringThe first character of every whitespace-separated word, joined with no separator. Upper-cased when $capitalize is true, otherwise returned with the original casing.
Errors
Nothing.
Str::initials splits on runs of whitespace, takes the first character of each chunk with mb_substr(), and concatenates them. Because the split is multibyte-aware, accented and non-Latin first letters survive intact.
When to reach for it
The standard use is an avatar placeholder: a coloured circle with the user's monogram when no uploaded image exists. It is also handy for compact table columns, chat participant chips, and abbreviating long department or project names in a breadcrumb.
What trips people up
The output has no separators. Str::initials('taylor otwell') is 'to' — not 'T.O.', not 'T. O.'. It also does not change case unless you pass capitalize: true, so lower-cased database values come back lower-cased.
Every whitespace-separated chunk contributes a letter, with no limit. 'Mary Jane von Trapp' gives four characters, and a name with a middle initial or a suffix such as 'Jr.' will produce more letters than the two-character circle in your design allows. Cap it yourself with Str::substr($initials, 0, 2), or take only the first and last words. Punctuation is not stripped either, so '(Anonymous)' yields '('.
Example
When to use it
- Render a monogram avatar placeholder when a user has not uploaded a photo.
- Abbreviate a long project or department name in a breadcrumb.
- Produce short participant chips for a chat or presence indicator.
Frequently asked questions
How do I get initials from a full name in Laravel?
Str::initials($name, capitalize: true) returns one upper-cased letter per whitespace-separated word, so 'taylor otwell' gives 'TO'.
Does Str::initials add dots between the letters?
No. The letters are joined with no separator at all, so the result is 'TO' rather than 'T.O.' or 'T. O.'. Insert separators yourself if you need them.
How do I limit Str::initials to two characters?
It has no limit argument, so reduce the input first — keep only the first and last word — or truncate the result with Str::substr($initials, 0, 2).
More examples
A two-character avatar monogram
Reducing to the first and last word before calling initials is what keeps the output at most two characters. Calling Str::initials directly on the four-word name would have produced 'MJVT' and overflowed a fixed-width badge.
<?php
use Illuminate\Support\Str;
function monogram(string $name): string
{
$words = preg_split('/\s+/', trim($name), -1, PREG_SPLIT_NO_EMPTY);
// First and last word only, so middle names never overflow the circle.
$name = count($words) > 1
? $words[0] . ' ' . end($words)
: ($words[0] ?? '');
return Str::initials($name, capitalize: true);
}
foreach (['taylor otwell', 'Mary Jane von Trapp', 'Prince', ''] as $n) {
printf("%-22s [%s]\n", "'{$n}'", monogram($n));
}
// 'taylor otwell' [TO]
// 'Mary Jane von Trapp' [MT]
// 'Prince' [P]
// '' []Normalising accents for a CSS-safe class
initials preserves the accented first letter, which is right for display. Passing that through Str::ascii gives a plain-ASCII variant suitable for a generated filename or a colour-hashing key that must not depend on encoding.
<?php
use Illuminate\Support\Str;
$names = ['Émile Zola', 'Ángel Ramírez', 'Zoë Saldaña'];
foreach ($names as $name) {
$display = Str::initials($name, capitalize: true);
$ascii = Str::upper(Str::ascii($display));
echo $name, ' => display ', $display, ', ascii ', $ascii, "\n";
}
// Émile Zola => display ÉZ, ascii EZ
// Ángel Ramírez => display ÁR, ascii AR
// Zoë Saldaña => display ZS, ascii ZS
Discussion