# TextItem

A text component with built-in overflow handling and auto-tooltips. When text is truncated, a tooltip automatically appears on hover showing the full content. Also supports text highlighting for search results.

## When to Use

- Display text that may overflow its container with automatic tooltip fallback
- Show search results with highlighted matching terms
- Labels or descriptions in constrained layouts (sidebars, tables, lists)
- Any text that needs ellipsis truncation with accessible full-text disclosure

## Component

---

### Properties

- **`highlight`** `string` — String to highlight within children (only works when children is a plain string)
- **`highlightCaseSensitive`** `boolean` (default: `false`) — Whether highlight matching is case-sensitive
- **`highlightStyles`** `Styles` — Custom styles for highlighted text portions
- **`tooltip`** `string | boolean | TooltipProviderProps` (default: `true`) — Tooltip configuration. `true` enables auto tooltip on overflow, a string shows fixed tooltip text, an object supports advanced configuration.
- **`tooltipPlacement`** `Placement` (default: `top`) — Default tooltip placement
- **`monospace`** `boolean` — Use monospace font
- **`ellipsis`** `boolean` — Truncate overflow with ellipsis
- **`nowrap`** `boolean` — Prevent text wrapping
- **`italic`** `string` — Font style (e.g. `'italic'`)
- **`weight`** `string | number` — Font weight
- **`transform`** `string` — Text transform (e.g. `'uppercase'`, `'capitalize'`)

### Base Properties

Supports [Base properties](../../BaseProperties.md) and all Text style properties including `preset`, `color`.

### Styling Properties

#### styles

Customizes the root text element. Inherits all styling capabilities from the Text component.

### Style Properties

These properties allow direct style application without using the `styles` prop:

- **Base:** `display`, `font`, `preset`, `hide`, `whiteSpace`, `opacity`, `transition`
- **Color:** `color`, `fill`, `fade`, `image`
- **Text:** `textTransform`, `fontWeight`, `fontStyle`

## Examples

### Basic Usage

```jsx
<TextItem>Simple text content</TextItem>
```

### Overflow with Auto-Tooltip

When text overflows its container, hovering reveals a tooltip with the full content:

```jsx
<Block width="200px">
  <TextItem>
    This is a very long text that will be truncated with ellipsis
    and show a tooltip on hover
  </TextItem>
</Block>
```

### Text Highlighting

Highlight matching text within the content - useful for search results:

```jsx
<TextItem highlight="search">
  Search results with highlighted text matching your query
</TextItem>
```

### Custom Highlight Styles

Customize the appearance of highlighted text with `highlightStyles`:

```jsx
<TextItem 
  highlight="important" 
  highlightStyles={{ fill: '#purple.20', color: '#purple' }}
>
  This important text has custom highlight styling
</TextItem>
```

### Case-Sensitive Highlighting

By default, highlighting is case-insensitive. Enable case-sensitive matching with `highlightCaseSensitive`:

```jsx
{/* Case-insensitive (default) - matches TEXT, text, Text */}
<TextItem highlight="text">
  TEXT and text and Text are all highlighted
</TextItem>

{/* Case-sensitive - only matches exact case */}
<TextItem highlight="text" highlightCaseSensitive>
  TEXT and text and Text - only lowercase is highlighted
</TextItem>
```

### Multiple Highlights

All occurrences of the highlight string are highlighted:

```jsx
<TextItem highlight="fox">
  The quick brown fox jumps over the lazy fox
</TextItem>
```

### Custom Tooltip

Override the auto-tooltip with custom content:

```jsx
<TextItem tooltip="Custom tooltip text that differs from the content">
  Short text
</TextItem>
```

### Disabled Tooltip

Disable the tooltip entirely:

```jsx
<TextItem tooltip={false}>
  This text will truncate but won't show a tooltip
</TextItem>
```

### Tooltip Placement

Control where the tooltip appears:

```jsx
<TextItem tooltipPlacement="bottom">
  Tooltip appears below on hover
</TextItem>
```

### With Text Styles

Apply typography and color styles:

```jsx
<TextItem preset="h3">Heading style</TextItem>
<TextItem preset="t2" color="#purple">Colored text</TextItem>
<TextItem weight="bold">Bold text</TextItem>
```

### Search Results List

Common pattern for filterable lists with highlighted search terms:

```jsx
const items = ['Apple', 'Application', 'Banana', 'Apply', 'Grape'];
const searchTerm = 'app';

<Space flow="column" gap="0.5x">
  {items.map((item) => (
    <TextItem key={item} highlight={searchTerm}>
      {item}
    </TextItem>
  ))}
</Space>
```

## Accessibility

### Keyboard Navigation

- `Tab` - Moves focus to the component (when tooltip is enabled)
- Tooltip content is accessible via focus, not just hover

### Screen Reader Support

- Truncated text is fully accessible via tooltip
- Highlighted text uses semantic `<mark>` element for screen reader announcement
- Tooltip content is announced when triggered

### ARIA Properties

- Tooltip trigger automatically manages `aria-describedby` for tooltip association

## Best Practices

1. **Do**: Use for text that may exceed container width
   ```jsx
   <Block width="200px">
     <TextItem>Long filename-that-might-overflow.tsx</TextItem>
   </Block>
   ```

2. **Do**: Provide meaningful highlight terms for search
   ```jsx
   <TextItem highlight={userSearchQuery}>{result.title}</TextItem>
   ```

3. **Don't**: Use for multi-line text (this component enforces single-line with ellipsis)
   ```jsx
   {/* Use Text component instead for multi-line content */}
   <Text>Multi-line paragraph content...</Text>
   ```

4. **Don't**: Disable tooltips for important truncated content
   ```jsx
   {/* Users won't be able to see the full text */}
   <TextItem tooltip={false}>Important information that gets cut off...</TextItem>
   ```

## Related Components

- Text - Base text component without overflow handling
- [Item](./Item.md) - Interactive list item with similar overflow behavior
- [TooltipProvider](../overlays/Tooltip.md) - Standalone tooltip wrapper

