Circle() - CSS Function

Syntax diagram of circle().

On the diagram, the terms in bold are the predefined terms in CSS, the others are described below:

• r is a positive or zero numerical value, followed by one of CSS dimension units.
• x and y are numerical values, followed by a unit of dimension.

Description of the circle() function.

The function circle() defines a circle, by indicating its radius, and optionally, its center relative to the element. This circle can be used in several ways, depending on the property that calls this circle():

• Used with clip-path, this circle can be used to cut out an element (for making round images, for example).
• With shape-outside, it can be used to define a wrapping shape.

The circle() value can be used with the following properties:

• clip-path : Defines the visible part of the element, delimited by a geometric shape (rectangle, polygon, etc.).
• offset-path : Defines the path on which an element can be positioned (Motion Path).
• shape-outside : Sets the shape of the text outline for a floating element.

Syntaxes of the circle() function.

• clip-path: circle(50px); r

  r is the radius of the circle. It is a numerical value, positive or zero, followed by a unit of relative or absolute dimension (see CSS dimension units). Percentages are calculated relative to the largest of the element's dimensions (width or height).

  r also accepts the following predefined values:

  1. farthest-side: the radius is equal to the distance from the center of the circle to the farthest edge.
  2. closest-side: the radius is equal to the distance from the center of the circle to the nearest edge.

  
  Effect of the closest-side value

  
  Effect of the value farthest-side

  If no value is specified, the function circle() takes the default value closest-side.

• clip-path: circle(50px at 20% 30%); r x y

  x and y are introduced by the word at. They indicate the coordinates of the center of the circle, measured from the left edge and the top edge of the element.

  x and y are positive or negative numeric values, followed by a relative or absolute unit of measurement (see CSS dimension units). If they are percentages, these are calculated relative to the width of the element for x and relative to the height of the element for y. Negative values are allowed and position the center of the circle outside the element.

  x and y also accept the following predefined values:
      - left, center or right for x
      - and top, center or bottom for y.

  For these two parameters, the default value is center.

Animation with the circle() function.

Here is a little amusement that mimics the movement of a light spot partially revealing the CSS3 logo. In fact, there are two superimposed images; the one underneath is heavily darkened, while the one on top is cut out with the clip-path property and the circle() function whose parameters are animated.

Simulator.

The image below measures 280 pixels in width and 210 pixels in height. Play with the parameters of the function circle() to fully understand how it works. In particular, test the parameters closest-side and farthest-side.

Browsers compatibility with circle() function.

No compatibility issues have been reported with recent or commonly used browsers.

1

Basic
shapes

2

circle()
function

Estimated overall support.

97%

95%

Browsers on computers :

Mobile browsers :

Outdated or marginal browsers :

Internet Explorer

UC Browser pour Androïd

Opéra Mobile

QQ Browser

Baidu Browser

Opéra

Samsung Internet

Chrome

Safari

Firefox

Safari sur IOS

Edge

Androïd Brower

Firefox pour Androïd

Chrome pour Androïd

KaiOS Browser

Opéra mini

See Caniuse.com for more compatibility information.

Caniuse

Caniuse

Historic of the circle() function.

• CSS Shapes Module Level 1

  This specification module defines all the predefined shapes usable in CSS: circle, rectangle, ellipse, polygon, complex shapes generated from SVG. It also presents some properties for using these shapes.

  Regarding circle(). Definition of the circle() function.
  

  June 20, 2013

  Working Draft.

  

  March 20, 2014

  Candidate Recommendation.

  

  

See also, in the same standardization module as circle().

The CSS specifications edited by the W3C are organized into modules. circle() is part of CSS Shapes Module. The following definitions are also described in this same module.

Properties:

shape-image-threshold

Sets the transparency threshold for the wrapping of an image.

shape-margin

Sets the margin for wrapping a floating element.

shape-outside

Sets the shape of the text outline for a floating element.

Functions:

Circle()

Defines a circle that can be used to clip an element or set a circumvention margin.

ellipse()

Defines an ellipse from the rays and the coordinates of the center.

inset()

Defines a rectangle, which can be used to cut out an element.

path()

Defines an outline based on the SVG syntax of a path.

polygon()

Defines a shape from a series of points expressed by their X and Y coordinates.

shape()

Defines any shape, composed of straight line segments or curves, which can be used, for example, with the clip-path property.

xywh()

Defines a rectangle, optionally with rounded corners, based on the dimensions of an element.