# react-truncate-inside: full documentation
react-truncate-inside is a React component that truncates text in the middle with an ellipsis, so a long string such as a file name, hash or wallet address keeps both its beginning and its end visible. The middle ellipsis is placed by measuring the real rendered width, and it is recomputed when the container resizes.
- npm: https://www.npmjs.com/package/react-truncate-inside
- Source (MIT license): https://github.com/zhiyuc123/react-truncate-inside
- Documentation site: https://zhiyuc123.github.io/react-truncate-inside/
- Online demo (Storybook): https://zhiyuc123.github.io/react-truncate-inside/storybook/?path=/docs/demo--docs
- README in Chinese: https://github.com/zhiyuc123/react-truncate-inside/blob/main/README.zh-CN.md
## Features
- Middle truncation: keeps the start of the text and the last `offset` characters (default 8), and replaces the overflow in between with `ellipsis` (default `...`).
- Measures the real width: text is measured on an off-screen canvas using the element's computed font (weight, style, size, family), so the result fits the actual rendered width instead of a character count.
- Responsive: re-truncates when the container is resized (`ResizeObserver`), when the `width` or `text` props change, and when web fonts finish loading.
- Unicode-safe: text is sliced by code point, so emoji and other surrogate pairs are never cut in half.
- Server rendering safe: nothing touches `document` or `window` during render; the server outputs the full text and the browser truncates it after mount.
- TypeScript: ships type declarations, including the exported `TruncateProps` interface.
- Tiny: zero runtime dependencies, about 1 kB minified and gzipped, published as both CommonJS and ES modules. Requires React 16.8 or newer (hooks).
## When to use
Use middle truncation whenever the end of a string carries information: an extension, a checksum suffix, the last characters that tell two similar values apart. The number of characters kept at the end is set with `offset`; how many characters of the start survive depends on the available width.
| Use case | Original | Truncated | offset |
| --- | --- | --- | --- |
| File names | ECMA-402_9th_edition_june_2022.pdf | ECMA-402_9th...2022.pdf | 8 |
| Hashes | a94a8fe5ccb19ba61c4c0873d391e987982fbbd3 | a94a8fe5cc...2fbbd3 | 6 |
| Wallet addresses | 0x71C7656EC7ab88b098defB751B7401B5f6d8976F | 0x71C7656E...976F | 4 |
| URLs | https://example.com/docs/guides/getting-started/installation | https://example.com/do...installation | 12 |
| File paths | /Users/alice/Projects/client/src/components/Header.tsx | /Users/alice/Proj...Header.tsx | 10 |
## Install
```bash
npm install react-truncate-inside
# or
yarn add react-truncate-inside
# or
pnpm add react-truncate-inside
```
## Quick start
```jsx
import React from 'react';
import Truncate from 'react-truncate-inside';
export default function Demo() {
return ;
}
```
Renders a 100 px wide element containing something like `An-...name.pdf`; how many leading characters survive depends on the font.
## API
The package has one default export, the `Truncate` component, and exports the `TruncateProps` interface.
```ts
import Truncate from 'react-truncate-inside';
import type { TruncateProps } from 'react-truncate-inside';
interface TruncateProps {
/** Text to be truncated. */
text: string;
/** Width of the element in px. When omitted the component fills its parent
and re-truncates whenever the parent is resized. */
width?: number;
/** Number of characters kept at the end of the text, i.e. the position of
the ellipsis counted from the end. Default: 8 */
offset?: number;
/** String inserted where characters were removed. Default: '...' */
ellipsis?: string;
}
```
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| text | string | required | The text to display. |
| width | number | parent width (100%) | Width of the element in px. When omitted the element fills its parent and re-truncates whenever the parent is resized. |
| offset | number | 8 | Number of characters kept at the end of the text. The ellipsis is inserted this many characters from the end. |
| ellipsis | string | '...' | String inserted where characters were removed. Only present when the text is actually truncated. |
The component renders `
` with the (possibly truncated) text as its only child. It does not forward other attributes.
## Examples
### TypeScript
```tsx
import React from 'react';
import Truncate from 'react-truncate-inside';
import type { TruncateProps } from 'react-truncate-inside';
type FileNameProps = Pick
& { name: string };
export function FileName({ name, width }: FileNameProps) {
// Keep the extension plus a few characters in front of it.
return ;
}
```
### Fill the parent and follow its width
Omit `width` and the element takes the full width of its parent. A `ResizeObserver` re-truncates the text whenever that width changes, for example when a sidebar is dragged or the window is resized.
```jsx
function Sidebar({ fileName }) {
return (
);
}
```
### Show the full text on hover
The component renders a single `div` and does not forward extra attributes, so put the `title` on a wrapper element.
```jsx
function FileLabel({ fileName }) {
return (
);
}
```
### In a table cell
Give the column a width (or use `table-layout: fixed`). With automatic table layout the cell grows to fit the full text, so there is nothing to truncate.
```jsx
function FileTable({ files }) {
return (
{files.map((file) => (
|
|
{file.size} |
))}
);
}
```
## How it works
The component renders the text in a `div` with `white-space: nowrap` and measures it with an off-screen `