CircularText

InstallationCopy Anchor Link

CircularText ships with the library — install it once, then import:

import { CircularText } from "@delacour/react-native-ui/circular-text";

Or copy the source into your project, to own and edit it:

bunx delacour@latest add circular-text

UsageCopy Anchor Link

import { CircularText } from "@/components/ui/circular-text";
import { Icon } from "@/components/ui/icon";
import { IconStar } from "@/lib/icons/central";
import { View } from "react-native";

export default function Example() {
  return (
    <View className="flex-1 items-center justify-center p-4">
      <CircularText
        centerContent={<Icon icon={IconStar} size="xl" />}
        radius={72}
        repeat="fill"
        spin={{ kind: "loop" }}
      >
        DELACOUR UI
      </CircularText>
    </View>
  );
}

SpanningCopy Anchor Link

span decides how much of the circle the words cover.

<CircularText radius={64} size="sm" span={{ kind: "arc", sweep: 140 }}>
  Handmade in Wellington
</CircularText>

Direction and sideCopy Anchor Link

side points glyph tops away from the centre (outside) or toward it (inside); direction is only the way a loop turns.

<CircularText radius={52} side="inside">TOP CONTRIBUTOR</CircularText>
<CircularText direction="counterclockwise" radius={52} spin={{ kind: "loop" }}>
  TOP CONTRIBUTOR
</CircularText>

SpinningCopy Anchor Link

spin is none (default), loop at speed degrees per second, or controlled by a SharedValue<number> your app drives from a scroll offset, a gesture or a slider.

<CircularText radius={72} spin={{ kind: "loop", speed: 24 }}>…</CircularText>
<CircularText radius={72} spin={{ kind: "controlled", rotation }}>…</CircularText>

PausingCopy Anchor Link

press eases the ring to a halt under a finger, controlled from your state; either resumes from the same angle.

<CircularText pause={{ kind: "press" }} radius={72} spin={{ kind: "loop", speed: 48 }}>
  PRESS AND HOLD
</CircularText>

Content in the middleCopy Anchor Link

centerContent stays upright, still and independently focusable while the ring turns.

<CircularText centerContent={<Avatar name="Aria Whitlock" size="xl" />} radius={52} repeat="fill">
  TOP CONTRIBUTOR
</CircularText>

Repeating a phraseCopy Anchor Link

repeat writes children that many times with separator after each; "fill" estimates enough copies to close the ring.

<CircularText radius={44} repeat="fill" separator=" · " spin={{ kind: "loop", speed: 60 }}>
  UPLOADING
</CircularText>

RecipesCopy Anchor Link

Seal — a filled ring around an icon, turning slowly: repeat="fill", spin={{ kind: "loop" }}, an Icon as centerContent.

Two rings — pass one CircularText as another's centerContent, the inner one smaller, direction="counterclockwise" and faster.

Badge — a muted ring around an Avatar, side="inside" for words along the bottom.

Loading ring — a Spinner in the middle and the action's name around it; the ring doubles as the accessible label for the wait.

Reduced motionCopy Anchor Link

Under reduce motion or isMotionCalm, a loop holds still at 0°; a controlled spin still follows its value.

AccessibilityCopy Anchor Link

• A screen reader hears the words once, separators stripped — "DELACOUR • UI • " is read "DELACOUR UI". Pass accessibilityLabel to say something else.
• Keep ring text at 12pt or more and under about 28 characters per half circle.

API ReferenceCopy Anchor Link

CircularTextCopy Anchor Link

Accepts every View prop except children.