# ASCII logo

An SVG or PNG logo redrawn in crisp glyphs, with shimmer, scan and reveal animations.

> 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. The asciicn agent skill, for building any ASCII effect on the engine, is at [/.well-known/agent-skills/asciicn/SKILL.md](/.well-known/agent-skills/asciicn/SKILL.md).

> **This is an example, not the only option.** It is one component built on the asciicn engine. Install it when it is what you were asked for. For any other look, don't stretch its props to fit: write your own field on `AsciiShader` ([Write your own](/docs/engine/write-your-own.md)), or draw a CPU grid with `AsciiGrid`, and read this example's source for technique. Its full source is in [https://asciicn.dev/r/ascii-logo.json](https://asciicn.dev/r/ascii-logo.json), under `files[].content`.

## Installation [#installation]

```bash
npx shadcn@latest add https://asciicn.dev/r/ascii-logo.json
```

## Usage [#usage]

```tsx
import { AsciiLogo } from "@/components/asciicn/ascii-logo";

export function Brand() {
  return (
    <AsciiLogo
      src="/brand/wordmark.svg"
      alt="Acme"
      effect="shimmer"
      className="h-16"
    />
  );
}
```

The logo's coverage decides where glyphs go: a transparent pixel stays empty and a solid one draws the densest glyph. Braille is the default because its 2×4 dots per cell keep letterforms readable down to small sizes. `charset="edge"` outlines the shapes with `- / | \` strokes.

Give the logo a height (or a width) and it keeps the file's own aspect ratio once it loads. Pass `ratio` to reserve the space before then. Without `cell`, the cell is about a tenth of the logo's height.

For a dark logo on an opaque white background, such as a JPEG, set `source="dark"`. `tone="original"` keeps the file's own colours.

## Examples [#examples]

### A row of logos [#a-row-of-logos]

Eight logos scanning in turn: `phase` offsets each one's sweep.



### Edge strokes and blocks [#edge-strokes-and-blocks]

Sobel strokes for an outline, and ANSI blocks through the ember ramp that assemble once on load.

```tsx title="examples/ascii-logo-edge.tsx"
import { AsciiLogo } from "@/components/asciicn/ascii-logo";

export default function AsciiLogoEdge() {
  return (
    <div className="flex w-full max-w-2xl flex-col gap-8">
      <AsciiLogo
        src="/examples/logos/orbitline.svg"
        alt="Orbitline"
        ratio={166 / 40}
        charset="edge"
        edgeThreshold={0.3}
        color="blue"
        cell={9}
        className="w-full"
      />
      <AsciiLogo
        src="/examples/logos/lumenade.svg"
        alt="Lumenade"
        ratio={203 / 40}
        charset="blocks"
        colorMode="duotone"
        ramp="ember"
        effect="reveal"
        cell={8}
        className="w-full"
      />
    </div>
  );
}
```

## Props [#props]

Every [ASCII image](/docs/images/ascii-image#props) look prop also applies. `charset` defaults to `"braille"` and `background` to `"transparent"`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `src` | `string` |  | SVG or PNG URL. Files on another origin need CORS headers. |
| `alt` | `string` |  | The brand name, read by screen readers. "" hides it. |
| `color` | `AsciiColor` | `"ink"` | Glyph colour in mono. |
| `tone` | `"mono" \| "original"` | `"mono"` | One ink, or the file's own colours. |
| `source` | `"alpha" \| "dark"` | `"alpha"` | alpha: the logo is the opaque part of the file. dark: the logo is the dark part of an opaque image. |
| `charset` | `CharsetName` | `"braille"` | Which glyphs draw the logo. |
| `effect` | `"none" \| "shimmer" \| "scan" \| "reveal"` | `"none"` | shimmer sweeps a band of solid glyphs across. scan runs a line down and leaves solid glyphs behind. reveal assembles the logo once, left to right. |
| `period` | `number` | `6` | Seconds per shimmer or scan. |
| `phase` | `number` | `0` | Where in the sweep this logo starts, 0 to 1. Offsets logos in a row. |
| `cell` | `number` | `a tenth of the height, 4 to 12` | Glyph cell height in CSS pixels. |
| `ratio` | `number` | `the file's ratio` | Width over height, to reserve space before the file loads. |
| `lazy` | `boolean` | `true` | Load only when the logo nears the viewport. Turn it off inside a clipped, moving row. |
| `handle` | `RefObject<AsciiHandle \| null>` |  | Filled with a handle for export. |

## Notes [#notes]

* The wrapper is announced as an image named by `alt`. Inside a link that already names the brand, pass `alt=""`.
* Effects stop under reduced motion, and the logo draws once. They also pause offscreen and in hidden tabs.
* A logo with no effect draws once per size or prop change and runs no frame loop.