Circle

Draws a perfect circle or arc within the available area, suitable for circular progress and meter scales. The diameter takes the smaller value of width and center. startAngle and sweepAngle control the display range. When the entire circle is closed, the background can be filled.

Example

function main() {
  return (
    <Circle
      width={120}
      height={120}
      background="clear"
      stroke={$env.accent}
      lineWidth={8}
      startAngle={-90}
      sweepAngle={240}
      strokePosition="inside"
    />
  );
}

Usage

Circle draws a centered circle using the smaller dimension. A 160×100 area produces a 100-point circle, not an ellipse. startAngle/sweepAngle change its contour; transform changes the completed drawing.
Angles use degrees: 0 right, 90 down, positive sweeps clockwise. startAngle wraps modulo 360; sweepAngle preserves direction and clamps to −360…360. Zero draws nothing; ±360 closes a full turn. startAngle transitions may use wrap:360; sweepAngle cannot.
Ellipse and Arc use the entire width×height bounds; equal dimensions make a circle. Partial sweeps stay open and do not connect to the center as a sector. background fills only a complete closed revolution.

Properties

startAngle?number

Start angle in degrees, wrapped modulo 360 when sampled.

Example0

sweepAngle?number

Sweep in degrees, clamped to -360…360 when sampled. Positive is clockwise; wrap is unsupported.

Example360

background?Paint

Fill paint for a closed full circle or ellipse. Ignored for partial arcs.

ExampleHDR($env.dark ? "white" : "black")

stroke?Paint

Stroke paint; accepts a color or gradient. Use clear to hide the stroke.

Example"clear"

lineWidth?number

Stroke thickness in points; 0 draws no stroke.

Example2

strokePosition?"inside" | "center" | "outside"

Stroke placement relative to the full circle or ellipse contour. Defaults to inside.

Example"inside"

lineCap?"round" | "butt" | "square"

Stroke end shape: butt stops at the endpoint, square extends it, round rounds it.

Example"round"

dash?number[]

Alternating painted and empty lengths in points; an empty array makes a solid stroke.

Example[]

dashPhase?number

Offset along the dash pattern, in points.

Example0

Common properties

width?number | "auto" | "fill"

Width in points, auto sizing or parent fill.

Example"fill"

height?number | "auto" | "fill"

Height in points, auto sizing or parent fill.

Example"fill"

x?number

Visual offset in points: x moves right, y moves down. Does not change layout space.

Example0

y?number

Visual offset in points: x moves right, y moves down. Does not change layout space.

Example0

transform?ViewTransform

Transform the whole View without changing layout. Translation uses points; rotation/skew use degrees; scale 1 is unchanged; anchors use 0–1.

Example{rotation: 0}

opacity?number

Opacity of the whole View: 0 is transparent, 1 is opaque.

Example1

clipped?boolean

Clip drawing that extends beyond the View bounds.

Examplefalse

clip?"rectangle" | "ellipse"

Clipping shape: rectangle or ellipse. Material also accepts false to disable clipping.

Example"rectangle"

mask?View | null

Alpha mask View. Centered without affecting layout; null disables masking.

Example<Circle width="fill" height="fill" background="white"/>

zIndex?number

Drawing order among siblings; larger values appear in front.

Example0

blur?number

Blur radius in points; 0 disables blur.

Example4

innerShadow?DrawingEffect

Effect color, opacity, blur radius and x/y offset. Distances are in points.

Example{color: HDR("black"), opacity: 0.5, radius: 4, x: 0, y: 2}

glow?DrawingEffect

Effect color, opacity, blur radius and x/y offset. Distances are in points.

Example{color: HDR("cyan"), radius: 8, opacity: 0.8}

shadowColor?Color

Color of the outer shadow.

ExampleHDR("black")

shadowOpacity?number

Outer shadow opacity from 0 to 1; 0 hides it.

Example0

shadowRadius?number

Outer shadow blur radius in points.

Example4

shadowX?number

Outer shadow offset in points: x right, y down.

Example0

shadowY?number

Outer shadow offset in points: x right, y down.

Example2

animations?CircleAnimation[]

Animate a supported property when it changes. duration/delay use seconds; from/to set endpoints; repeat and autoreverse control repetition; wrap sets a periodic range.

Example[{property: "opacity", duration: 0.25, curve: "easeInOut"}]

key?string | number

Stable identity among siblings.

Practical example

function main() {
  return (
    <ZStack width={140} height={140}>
      <Circle
        width="fill"
        height="fill"
        background="clear"
        stroke="#88888833"
        lineWidth={10}
      />
      <Circle
        width="fill"
        height="fill"
        background="clear"
        stroke={$env.accent}
        lineWidth={10}
        startAngle={-90}
        sweepAngle={270}
        lineCap="round"
      />
      <Text fontSize={36}>75%</Text>
    </ZStack>
  );
}

Animation

widthheightxyopacitybackgroundblurshadowColorshadowOpacityshadowRadiusshadowXshadowYdashPhasestrokelineWidthstartAnglesweepAngletransform.translateXtransform.translateYtransform.scaleXtransform.scaleYtransform.rotationtransform.skewXtransform.skewYtransform.anchorXtransform.anchorY

When omitted

The table lists omission behavior verified against implementation. Property examples are copyable syntax, not defaults. Pass explicit values for a fixed result; contextual dimensions and theme colors are not fixed constants.

Properties	When omitted
`startAngle`	`0`
`sweepAngle`	`360`
`lineWidth`	`2`
`strokePosition`	`"inside"`
`background`	`HDR($env.dark ? 'white' : 'black')`

Example

Usage

Properties

Practical example

Animation

When omitted

Arc

Ellipse

Animation

Color / Gradient

On this page

Circle

Example

Usage

Properties

Practical example

Animation

When omitted

Related APIs

Arc

Ellipse

Animation

Color / Gradient

On this page