# Caret

A blinking text caret — a controlled vertical bar or a self-animating blink.

> For the complete documentation index, see [llms.txt](/llms.txt). Markdown variants are available by appending `.md` to any URL or sending an `Accept: text/markdown` header. An agent skill is available at [/.well-known/agent-skills/site-skill.md](/.well-known/agent-skills/site-skill.md).

## Installation

<TabsTrigger value="cli">Command</TabsTrigger>
<TabsTrigger value="manual">Manual</TabsTrigger>

```bash
npx shadcn@latest add @framecn/caret
```

<Step>Copy and paste the following code into your project.</Step>

<Step>Update the import paths to match your project setup.</Step>

## Usage

Controlled — the consumer decides visibility:

```tsx
import { Caret } from "@/components/ui/caret";

<Caret color="#1F1E1D" height={24} opacity={typing ? 1 : 0} />;
```

Standalone blink — a self-animating caret driven by `useCurrentFrame()`:

```tsx
import { Caret } from "@/components/ui/caret";

<Caret blink blinkPerSecond={1} height={28} />;
```

The docs preview shows a blinking caret after placeholder text, matching remocn’s preview scene.

## How blink works

```
visible = floor(frame × speed / halfPeriod) is even
halfPeriod = fps / blinkPerSecond / 2
```

When `opacity` is provided it always wins; otherwise `blink` drives the bar, and with neither the caret stays solid.

## API Reference

### Caret

| Prop             | Type            | Default               |
| ---------------- | --------------- | --------------------- |
| `color`          | `string`        | `"currentColor"`      |
| `width`          | `number`        | `2`                   |
| `height`         | `number`        | `18`                  |
| `radius`         | `number`        | `1`                   |
| `opacity`        | `number`        | `-` (overrides blink) |
| `blink`          | `boolean`       | `false`               |
| `blinkPerSecond` | `number`        | `1`                   |
| `speed`          | `number`        | `1`                   |
| `marginLeft`     | `number`        | `0`                   |
| `className`      | `string`        | `-`                   |
| `style`          | `CSSProperties` | `-`                   |