> ## Documentation Index
> Fetch the complete documentation index at: https://neo.tvk.company/llms.txt
> Use this file to discover all available pages before exploring further.

# Fluid Text

> Animates string changes with staggered per-character motion — scale, slide, and blur — for smooth, polished text transitions.

## Examples

<Tabs>
  <Tab title="Basic Usage">
    <CodeGroup>
      ```dart Basic Fluid Text lines theme={null}
      NeoFluidText(
        label.value,
        style: theme.textStyles.header2,
      ),
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Custom Duration">
    <CodeGroup>
      ```dart Custom Duration lines theme={null}
      NeoFluidText(
        statusLabel.value,
        style: theme.textStyles.body1,
        duration: const Duration(milliseconds: 400),
      ),
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Multi-Line">
    <CodeGroup>
      ```dart Multi-Line lines theme={null}
      NeoFluidText(
        description.value,
        style: theme.textStyles.body2,
        maxLines: 2,
        overflow: .ellipsis,
      ),
      ```
    </CodeGroup>
  </Tab>
</Tabs>

## Properties

### Required

<ParamField path="data" type="String" required>
  The string to display. When this value changes, each character animates out from the old string and in from the new one with staggered scale, slide, and blur motion.
</ParamField>

### Content

<ParamField path="style" type="TextStyle">
  Text style for the rendered string. Merges with `DefaultTextStyle` — omitting this uses the ambient style.
</ParamField>

<ParamField path="maxLines" type="int">
  Maximum number of lines to render. Mirrors the `Text` widget's `maxLines` parameter.
</ParamField>

<ParamField path="overflow" type="TextOverflow">
  How to handle text that exceeds `maxLines` or the available width. Defaults to `.clip`.
</ParamField>

<ParamField path="softWrap" type="bool">
  Whether to wrap text at soft line breaks. Defaults to `true`.
</ParamField>

<ParamField path="textAlign" type="TextAlign">
  Horizontal alignment of the text within its bounding box.
</ParamField>

<ParamField path="textDirection" type="TextDirection">
  Reading direction. Defaults to the ambient `Directionality`.
</ParamField>

### Layout

<ParamField path="useMaxWidthDuringTransition" type="bool" default="false">
  When `true`, the widget holds the wider of the old and new text widths during the animation, preventing layout jumps when surrounding content is sensitive to size changes. When `false` (default), the width interpolates smoothly from old to new.
</ParamField>

### Styling

<ParamField path="duration" type="Duration">
  Override the animation duration. Defaults to `theme.durations.long`.
</ParamField>

## Best Practices

* **Stable style reference**: If you compute a `TextStyle` in `build`, make sure it is stable between builds when the text hasn't changed, otherwise the widget will restart the transition on every rebuild. Use `useMemoized` or a `const` style.
* **Semantic label**: `NeoFluidText` wraps its content in a `Semantics` widget with `label: data`, so screen readers announce the final string rather than individual characters animating.
* **Width stability**: Use `useMaxWidthDuringTransition: true` inside fixed-height containers where a momentary width change would cause sibling widgets to shift.

## Integration Notes

* `NeoFluidText` uses a custom `RenderObject` to measure intrinsic sizes from the actual text layout, matching `Text` widget sizing exactly.
* `NeoButton`, `NeoToast`, `NeoDropdownField`, and `NeoBadge` use `NeoFluidText` internally for their labels, so label copy changes animate automatically without any extra work.