artistic-text

A reusable React component and preset collection that reproduces the artistic text styles and animations from Artistic Text Studio.

Installation

pnpm add artistic-text
# or
npm install artistic-text
# or
yarn add artistic-text

Usage

1. Import the component and include the bundled styles:

import "artistic-text/styles.css"
import { ArtisticText } from "artistic-text"

2. Render the text with any preset combination:

<ArtisticText text="艺术字效果" styleId="gradient" animationId="lightSpeedInLeft" />

自定义字号（覆盖默认 clamp）：

<ArtisticText text="超大字号" styleId="gold" fontSize="80px" />

自定义字体粗细：

<ArtisticText text="更细一点" styleId="gold" fontWeight={400} />

也可以用 CSS 变量全局覆盖默认粗细（默认 700）：

.ats-text-base {
  --ats-font-weight: 500;
}

自定义预设（更强的配置能力）

有些效果（例如描边宽度/颜色）默认预设不一定满足某次需求。推荐用 CSS 变量 + 配置层来做“外部可配置、组件实现不改动”的自定义。

1. 单次使用：直接在 style 里覆盖 CSS 变量（不影响其他地方）：

<ArtisticText
  text="可自定义描边"
  styleId="white-stroke"
  style={{ ["--ats-stroke-color" as any]: "#111827", ["--ats-stroke-width" as any]: "clamp(2px, 0.08em, 6px)" }}
/>

2. 全局/页面级配置：用 ArtisticTextConfigProvider 给某个 styleId 统一注入覆盖（组件内部会自动合并）：

import { ArtisticTextConfigProvider } from "artistic-text"

<ArtisticTextConfigProvider
  value={{
    stylePresetStyles: {
      "white-stroke": {
        ["--ats-stroke-color" as any]: "#111827",
        ["--ats-stroke-width" as any]: "clamp(2px, 0.08em, 6px)",
      },
    },
  }}
>
  <ArtisticText text="同一个 styleId，但描边更粗" styleId="white-stroke" />
  <ArtisticText text="这里也会生效" styleId="white-stroke" />
</ArtisticTextConfigProvider>

除了 stylePresetStyles 外，也可以通过 stylePresets/fontPresets/animationPresets 覆盖或扩展内置的 id -> className 映射（只改你关心的 key，其他自动回退到内置预设）。

如果你希望“描边更像在字形外侧”（避免占用字形内部），可以将描边切换为 SVG 渲染（仅推荐用于描边类样式）：

<ArtisticText text="外描边感更强" styleId="fill-white-stroke-black" strokeRenderer="svg" />

样式/字体选择器

快速渲染预设缩略图并选择：

import { ArtisticTextSelector } from "artistic-text"

const [styleId, setStyleId] = useState("gradient")
const [fontId, setFontId] = useState("font-95")

<ArtisticTextSelector mode="style" value={styleId} onChange={setStyleId} previewText="T" />

<ArtisticTextSelector
  mode="font"
  value={fontId}
  onChange={setFontId}
  previewText="站"
  fontPreviewStyleId="white-stroke-shadow"
/>

默认使用完整预设列表，也支持传入 options 自定义组合。常用参数：

• mode：style | font
• value / onChange：受控选中项
• previewText：缩略字符（默认 T）
• fontPreviewStyleId：字体模式时给预览加描边/渐变
• showLabels、showNone、columns：控制标签、无样式项以及列数
• maxVisible：限制渲染的个数（从头部截断）
• options：自定义列表；或用 optionsMap（键作为 id）传入映射结构，字段可自定义 label/styleId/fontId
• 默认字体模式会显示语义化名称（如 “华文琥珀” 而非 font-14），可用 options/optionsMap 覆盖

需要自定义 UI 时，可通过导出的 fontLabels、textFontPresets 组合出自定义下拉或样式列表。

字体模式还可以用 variant="select" 以下拉形式展示，并让选项文字应用对应字体：

<ArtisticTextSelector mode="font" variant="select" value={fontId} onChange={setFontId} showNone />

CustomPicker（通用网格选择器）

包内还提供了一个轻量的选择器，可自定义缩略图、布局和“无样式”项：

import { CustomPicker, type PickerOption } from "artistic-text"

const options: PickerOption<string>[] = [
  { value: "none", label: "T", isNone: true },
  { value: "gold", label: "T", style: { backgroundColor: "#FFD700" } },
  { value: "red", label: "T", style: { backgroundColor: "#E74C3C", color: "#fff" } },
]

<CustomPicker options={options} onChange={(val) => console.log(val)} placeholder="T" />

参数与受控逻辑与上面的预设选择器类似，并支持 renderOption / renderSelected 来完全自定义渲染。

自定义字体 (fontId)

可通过 fontId 选择内置的中文字体，组件会自动注入所需的 @font-face 并设置字体族。示例：

<ArtisticText text="站酷快乐体" styleId="gold" fontId="font-97" animationId="shine" />

可选项：

• font-14（华文琥珀）
• font-15（华文隶书）
• font-16（华文新魏）
• font-17（华文行楷）
• font-23（濑户字体）
• font-24（庞门正道标题体）
• font-32（书体坊颜体）
• font-90（文泉驿正黑）
• font-94（杨任东竹石体）
• font-95（站酷高端黑）
• font-96（站酷酷黑）
• font-97（站酷快乐体）
• font-100（装甲明朝体）
• font-101（思源黑体粗体）
• font-102（思源黑体黑体）
• font-103（思源黑体细体）
• font-104（思源黑体纤细）
• font-105（思源黑体中黑）
• font-106（思源黑体常规）
• font-107（思源黑体极细）

预设文字样式 (styleId)

新增样式的详细参数（色值/描边宽度/投影偏移/圆角/内边距）见：packages/artistic-text/docs/style-params.md。

• gradient（渐变彩虹）
• neon（霓虹灯）
• 3d（3D 立体）
• glitch（故障风）
• outline（描边）
• offset-white-shadow-cyan（白字 + 青色错位投影）
• offset-white-shadow-pink（白字 + 粉色错位投影）
• offset-cream-shadow-red（浅黄字 + 红色错位投影）
• offset-red-shadow-yellow（红字 + 黄色错位投影）
• offset-black-shadow-green（黑字 + 绿色错位投影）
• bg-yellow-text-black（黄底黑字）
• bg-rose-text-white（红底白字）
• bg-black-text-mint（黑底薄荷绿字）
• bg-black-text-white（黑底白字）
• bg-white-text-black（白底黑字）
• bg-gray-stroke-pink（灰底粉描边空心字）
• fill-white-stroke-black（白字黑描边）
• fill-black-stroke-white（黑字白描边）
• fill-yellow-stroke-black（黄字黑描边）
• fill-cyan-stroke-black（青字黑描边）
• fill-pink-stroke-white（粉字白描边）
• fill-blue-stroke-white（蓝字白描边）
• fill-white-stroke-red-glow（白字粉描边发光）
• fire（火焰）
• ice（冰霜）
• gold（黄金渐变）
• chrome（金属）
• retro（复古）
• particle（粒子）
• rainbow-wave（彩虹波浪）
• white-stroke（白色描边）
• white-stroke-shadow（白描阴影）
• white-3d（白色立体）
• gold-stroke（金色描边）
• green-neon（绿色霓虹）
• yellow-gradient（黄色渐变）
• lime-gradient（黄绿渐变）
• yellow-stroke（黄色描边）
• gold-3d（金色立体）
• purple-stroke-shadow（紫描阴影）
• orange-3d（橙色立体）
• purple-stroke（紫色描边）
• cyan-neon（青色霓虹）
• red-3d-stroke（红色立体描边）
• green-neon-stroke（绿霓虹描边）
• white-3d-shadow（白立体阴影）
• teal-neon（青绿色霓虹）
• orange-gradient（橙黄渐变）
• yellow-3d-shadow（黄立体阴影）
• gold-3d-bold（金色立体粗）
• purple-gradient（紫色渐变）
• pink-stroke（粉色描边）
• gray-hollow（灰色空心）
• orange-fire（橙色火焰）

预设动画效果 (animationId)

• none（无动画）
• float（漂浮）
• bounce（弹跳进入）
• slide（滑入）
• rotate（旋转进入）
• wave（波浪，逐字延迟）
• typewriter（打字机，自动带光标闪烁）
• zoom（缩放脉冲）
• shake（抖动）
• flip（翻转）
• shine（扫光）
• wobble（晃动）
• blink（闪烁）
• light-bounce（轻微跳动）
• shout（呐喊）
• rubberBand（橡皮筋）
• jello（果冻）
• heartBeat（心跳）
• swing（摇摆）
• tada（惊喜）
• flash（闪现）
• pulse（脉动）
• backInDown（后退进入）
• bounceIn（弹入）
• fadeIn（淡入）
• zoomIn（放大进入）
• rollIn（滚入）
• fadeInDown（向下淡入）
• fadeInUp（向上淡入）
• fadeInLeft（向左淡入）
• fadeInRight（向右淡入）
• zoomInDown（向下放大进入）
• zoomInUp（向上放大进入）
• rotateInDownLeft（左下旋入）
• rotateInDownRight（右下旋入）
• lightSpeedInLeft（左侧光速）
• lightSpeedInRight（右侧光速）
• jackInTheBox（惊喜弹出）

The component also supports passing children to wrap custom markup, toggling loop behaviour with loop={false}, overriding the rendered element via as, and composing custom classes with styleClassName / animationClassName. You can set a custom font size with the fontSize prop (e.g. fontSize="80px"), which overrides the default clamp size while keeping other inline styles passed via style.

You can access the preset maps via the named exports textStylePresets, textAnimationPresets, and helper functions resolveStylePreset / resolveAnimationClass for advanced scenarios.

Tailwind integration

The package is self-contained and does not require TailwindCSS. If your project already uses Tailwind, you can still safelist the provided classes to keep purging tools from stripping them.

Building from source

pnpm build

The library ships ESM, CJS, and type declarations in dist/. Remember to publish both dist artifacts and styles.css when releasing.

发布到 npm

1. 确认版本号已在 package.json 中更新。
2. 执行 pnpm install 保证依赖齐全，然后在包目录运行 pnpm build（prepublishOnly 也会在发布前自动构建）。
3. 在 packages/artistic-text 下执行 npm publish --access public（构建产物位于 dist/index.js、dist/index.cjs、dist/index.d.ts、dist/styles.css，务必检查这些文件存在）。
4. 其他项目即可通过 pnpm add artistic-text 引入，并按照上面的用法导入组件和样式。