diff --git a/files/en-us/web/css/basic-shape/index.md b/files/en-us/web/css/basic-shape/index.md index ce6d383f4766a94..03b3e127aebe84a 100644 --- a/files/en-us/web/css/basic-shape/index.md +++ b/files/en-us/web/css/basic-shape/index.md @@ -97,7 +97,7 @@ The {{cssxref("basic-shape/polygon","polygon()")}} function defines a polygon us polygon( <`fill-rule`>?, [ ]# ) ``` -The function takes a list of comma-separated coordinate pairs, each consisting of two space-separated `` values as the _xi_ and _yi_ pair. These values represents the x and y axis coordinates of the vertex of the polygon at position _i_. +The function takes a list of comma-separated coordinate pairs, each consisting of two space-separated `` values as the _xi_ and _yi_ pair. These values represent the x and y axis coordinates of the polygon at position _i_ (the vertex point where two lines meet). ### Syntax for paths @@ -107,7 +107,7 @@ The {{cssxref("basic-shape/path","path()")}} function defines a shape using an S path( <`fill-rule`>?, ]? ) ``` -The required `` is an [SVG Path](/en-US/docs/Web/SVG/Attribute/d) as a quoted string. +The required `` is an [SVG path](/en-US/docs/Web/SVG/Attribute/d) as a quoted string. The `path()` function is not a valid {{cssxref("shape-outside")}} property value. ### Syntax for shapes {{Experimental_Inline}} @@ -117,27 +117,30 @@ The {{cssxref("basic-shape/shape","shape()")}} function defines a shape using an shape( ? from , # ) ``` -The `from ` parameter represents the starting point for the first shape command, and `` defines one one or more shape commands, which are similar to the [SVG path commands](/en-US/docs/Web/SVG/Attribute/d#path_commands). +The `from ` parameter represents the starting point for the first shape command, and `` defines one one or more shape commands, which are similar to the [SVG path commands](/en-US/docs/Web/SVG/Attribute/d#path_commands). The `shape()` function is not a valid {{cssxref("shape-outside")}} property value. ## Description When creating a shape, the reference box is defined by the property that uses `` values. The coordinate system for the shape has its origin at the top-left corner of the element's margin box by default, with the x-axis running to the right and the y-axis running downwards. All the lengths expressed in percentages are resolved from the dimensions of the reference box. -The default reference box is the [`margin-box`](/en-US/docs/Web/CSS/box-edge#margin-box), as demonstrated in the image below. The image shows a circle created using `shape-outside: circle(50%)` and inspected using a browser's Developer Tools, highlighting the different parts of the box model. The shape here is defined with reference to the margin-box. +The default reference box is the [`margin-box`](/en-US/docs/Web/CSS/box-edge#margin-box), as demonstrated in the image below. The image shows a circle created using `shape-outside: circle(50%)`, highlighting the different parts of the box model as seen in a browser's Developer Tools. The shape here is defined with reference to the margin-box. ![An image showing a circle inspected with the Firefox DevTools Shape Inspector. The different parts of the box model are highlighted.](shapes-reference-box.png) ### Computed values of basic shapes -The values in a `` function are computed as specified, with these exceptions: +The values in a `` function are computed as specified, with the following additional considerations: -- Omitted values are included and compute to their defaults. -- A {{cssxref("<position>")}} value in `circle()` or `ellipse()` is computed as a pair of offsets (horizontal then vertical) from the top left origin, each given as a combination of an absolute length and a percentage. -- A [``](/en-US/docs/Web/CSS/border-radius) value in `inset()` is computed as an expanded list of all eight {{cssxref("length")}} or percentage values. +- For any omitted values, their defaults are used. +- A {{cssxref("position_value", "<position>")}} value in `circle()` or `ellipse()` is computed as a pair of offsets from the top left corner of the reference box: the first offset is horizontal, and the second is vertical. Each offset is specified as a {{cssxref("length-percentage")}} value. +- A [``](/en-US/docs/Web/CSS/border-radius) value in `inset()` is expanded into a list of eight values, each either a {{cssxref("length")}} or a {{cssxref("percentage")}}. +- {{cssxref("basic-shape/inset","inset()")}}, {{cssxref("basic-shape/rect","rect()")}}, and {{cssxref("basic-shape/xywh","xywh()")}} functions compute to the equivalent `inset()` function. ### Interpolation of basic shapes -When animating from one `` to another, the {{Glossary("interpolation")}} rules listed below are followed. For any interpolation to happen between two shapes, both must use the same reference box. The values between two `` functions interpolate based on their computed values, forming a list. The values in the list are interpolated as {{cssxref("<number>")}}, {{cssxref("<length>")}}, {{cssxref("<percentage>")}}, {{cssxref("<angle>")}}, or {{cssxref("calc", "calc()")}} where possible. If the values are not one of those data types but are identical between the two interpolating basic shape functions, such as `nonzero`, those values also interpolate. +When animating between two `` functions, the {{Glossary("interpolation")}} rules listed below are followed. The parameter values of each `` function form a list. For interpolation to occur between two shapes, both shapes must use the same reference box and the number and type of values in both `` lists must match. + +Each value in the lists of the two `` functions is interpolated based on its computed value as a {{cssxref("number")}}, {{cssxref("length")}}, {{cssxref("percentage")}}, {{cssxref("angle")}}, or {{cssxref("calc", "calc()")}} where possible. Interpolation can still occur if the values are not one of those data types but are identical between the two interpolating basic shape functions, such as `nonzero`. - **Both shapes are of type `ellipse()` or type `circle()`**: Interpolation is applied between each corresponding value if their radii are specified as either a {{cssxref("length")}} or a {{cssxref("percentage")}} (rather than keywords such as `closest-side` or `farthest-side`). @@ -233,7 +236,7 @@ div { ## See also -- Properties that use this data type: {{cssxref("clip-path")}}, {{cssxref("shape-outside")}} +- Properties that use this data type: {{cssxref("clip-path")}}, {{cssxref("offset-path")}}, {{cssxref("shape-outside")}}, - [CSS shapes](/en-US/docs/Web/CSS/CSS_shapes) module - [Overview of CSS shapes](/en-US/docs/Web/CSS/CSS_shapes/Overview_of_shapes) - [Edit Shape Paths in CSS — Firefox Developer Tools](https://firefox-source-docs.mozilla.org/devtools-user/page_inspector/how_to/edit_css_shapes/index.html) diff --git a/files/en-us/web/css/basic-shape/path/index.md b/files/en-us/web/css/basic-shape/path/index.md index a29364e7387a198..1d3d697ca230fcb 100644 --- a/files/en-us/web/css/basic-shape/path/index.md +++ b/files/en-us/web/css/basic-shape/path/index.md @@ -29,8 +29,13 @@ path( [,]? ) - [``](/en-US/docs/Web/SVG/Attribute/fill-rule) {{optional_inline}} - - : An optional value of [`nonzero`](/en-US/docs/Web/SVG/Attribute/fill-rule#nonzero) (the default when omitted) or [`evenodd`](/en-US/docs/Web/SVG/Attribute/fill-rule#evenodd), which defines how the inside of the shape to be filled is determined. - > **Note:** `` is not supported in {{cssxref("offset-path")}} and using it invalidates the property. + - : Defines how the inside of the shape created by the path is to be filled. The possible values include: + + - `nonzero`: A point is considered inside the shape if a ray drawn from the point crosses more left-to-right than right-to-left path segments, resulting in a non-zero count. This is the default value when `` is omitted. + + - `evenodd`: A point is considered to be inside the shape if a ray drawn from the point crosses an odd number of path segments. This means that for each time the ray enters the shape, it has not exited an equal number of times, indicating an odd count of entries without corresponding exits. + + > **Warning:** `` is not supported in {{cssxref("offset-path")}} and using it invalidates the property. - {{cssxref("string")}} - : A [data string](/en-US/docs/Web/SVG/Attribute/d) for defining an [SVG path](/en-US/docs/Web/SVG/Element/path). The syntax for the contents of this `` is identical to SVG. diff --git a/files/en-us/web/css/basic-shape/shape/index.md b/files/en-us/web/css/basic-shape/shape/index.md index 364dde4aa523cd0..85ed9f0fa496347 100644 --- a/files/en-us/web/css/basic-shape/shape/index.md +++ b/files/en-us/web/css/basic-shape/shape/index.md @@ -44,7 +44,7 @@ offset-path: shape( ); clip-path: shape( - nonzero from 10px 10px, + evenodd from 10px 10px, curve to 60px 20% via 40px 0, smooth to 90px 0, curve by -20px 60% via 10% 40px 20% 20px, @@ -62,7 +62,7 @@ clip-path: shape( - `evenodd`: A point is considered to be inside the shape if a ray drawn from the point crosses an odd number of path segments. This means that for each time the ray enters the shape, it has not exited an equal number of times, indicating an odd count of entries without corresponding exits. - > **Note:** `` is not supported in {{cssxref("offset-path")}} and using it invalidates the property. + > **Warning:** `` is not supported in {{cssxref("offset-path")}} and using it invalidates the property. - `from ` @@ -74,39 +74,51 @@ clip-path: shape( The syntax of most shape commands is a keyword providing a directive, such as `move` or `line`, followed by the `by` or `to` keyword, and a set of coordinates. - `by`: Indicates that the `` is relative to the command's starting point ("relative" value). + `by`: Indicates that the `` is relative to the command's starting point (a "relative" value). - `to`: Indicates that the `` is relative to the top-left corner of the reference box ("absolute" value). + `to`: Indicates that the `` is relative to the top-left corner of the reference box (an "absolute" value). > **Note:** If a coordinate in a `` is specified as a percentage, the value is calculated relative to the respective width or height of the reference box. - The following ``s can be specified: + The following ``s can be specified: ``, ``, ``, ``, ``, ``, and `close`. - - ``: Specified as `move [by | to] `. This command adds a [MoveTo command](/en-US/docs/Web/SVG/Attribute/d#moveto_path_commands) to the list of shape commands. It draws nothing. Rather, it specifies the starting position for the next command. The `by` or `to` keyword specifies whether the `` point is "relative" or "absolute", respectively. If the `` follows the `close` command, it identifies the starting point of the next shape or subpath. + ``: Specified as `move [by | to] `. This command adds a [MoveTo command](/en-US/docs/Web/SVG/Attribute/d#moveto_path_commands) to the list of shape commands. It draws nothing. Rather, it specifies the starting position for the next command. The `by` or `to` keyword specifies whether the `` point is relative or absolute, respectively. If the `` follows the `close` command, it identifies the starting point of the next shape or subpath. - - ``: Specified as `line [by | to] `. This command adds a [LineTo command](/en-US/docs/Web/SVG/Attribute/d#lineto_path_commands) to the list of shape commands. It draws a straight line from the command's starting point to its ending point. The `by` or `to` keyword specifies whether the ending point specified by `` is "relative" or "absolute", respectively. + ``: Specified as `line [by | to] `. This command adds a [LineTo command](/en-US/docs/Web/SVG/Attribute/d#lineto_path_commands) to the list of shape commands. It draws a straight line from the command's starting point to its ending point. The `by` or `to` keyword specifies whether the ending point specified by `` is relative or absolute, respectively. - - ``: Specified as `[hline | vline] [by | to] `. This command adds a horizontal (`hline`) or vertical (`vline`) [LineTo command](/en-US/docs/Web/SVG/Attribute/d#lineto_path_commands) to the list of shape commands. With `hline`, a horizontal line is drawn from the command's starting point `to` or `by` the `x` position defined by ``. With `vline`, a vertical line is drawn from the command's starting point `to` or `by` the `y` position defined by ``. The `by` or `to` keyword determines the "relative" or "absolute" ending point, respectively. This command is equivalent to `` with one coordinate value set by the single `` and the other coordinate value remaining unchanged from its starting command. + ``: Specified as `[hline | vline] [by | to] `. This command adds a horizontal (`hline`) or vertical (`vline`) [LineTo command](/en-US/docs/Web/SVG/Attribute/d#lineto_path_commands) to the list of shape commands. With `hline`, a horizontal line is drawn from the command's starting point `to` or `by` the `x` position defined by ``. With `vline`, a vertical line is drawn from the command's starting point `to` or `by` the `y` position defined by ``. The `by` or `to` keyword determines the relative or absolute ending point, respectively. This command is equivalent to `` with one coordinate value set by the single `` and the other coordinate value remaining unchanged from its starting command. - - ``: Specified as `curve [by | to] via []`. This command adds a [Bézier curve command](/en-US/docs/Web/SVG/Attribute/d#cubic_bézier_curve) to the list of shape commands. The `by` or `to` keyword determines whether the ending point of the curve, specified by the first ``, is "relative" or "absolute", respectively. + ``: Specified as `curve [by | to] via []`. This command adds a [Bézier curve command](/en-US/docs/Web/SVG/Attribute/d#cubic_bézier_curve) to the list of shape commands. The `by` or `to` keyword determines whether the ending point of the curve, specified by the first ``, is relative or absolute, respectively. The `via` keyword specifies the control points of the Bézier curve. - The `via` keyword specifies the control points of the Bézier curve. If only a single `` is provided, the command draws a [quadratic Bézier curve](/en-US/docs/Web/SVG/Attribute/d#quadratic_bézier_curve), which is defined by three points (the start point, control point, and end point). If two `` values are provided, the command draws a cubic Bézier curve, which is defined by four points (the start point, two control points, and the end point). + - If only a single `` is provided, the command draws a [quadratic Bézier curve](/en-US/docs/Web/SVG/Attribute/d#quadratic_bézier_curve), which is defined by three points (the start point, control point, and end point). + - If two `` values are provided, the command draws a cubic Bézier curve, which is defined by four points (the start point, two control points, and the end point). - - ``: Specified as `smooth [by | to] [via ]`. This command adds a smooth [Bézier curve command](/en-US/docs/Web/SVG/Attribute/d#cubic_bézier_curve) to the list of shape commands. The `by` or `to` keyword determines whether the ending point of the curve, specified by the first ``, is "relative" or "absolute", respectively. + ``: Specified as `smooth [by | to] [via ]`. This command adds a smooth [Bézier curve command](/en-US/docs/Web/SVG/Attribute/d#cubic_bézier_curve) to the list of shape commands. The `by` or `to` keyword determines whether the ending point of the curve, specified by the first ``, is relative or absolute, respectively. - If `via ` is omitted, the command draws a smooth quadratic Bézier curve, which uses the previous control point and the current endpoint to define the curve. If the optional `via` keyword is included, it specifies the control points of the curve through ``, drawing a smooth cubic Bézier curve defined by the previous control point, the current control point, and the current endpoint. Smooth curves ensure a continuous transition from the shape, while quadratic curves do not. Smooth quadratic curves maintain a seamless transition using a single control point, whereas smooth cubic curves provide a more refined transition using two control points. + - If `via ` is omitted, the command draws a smooth quadratic Bézier curve, which uses the previous control point and the current endpoint to define the curve. + - If the optional `via` keyword is included, it specifies the control points of the curve through ``, drawing a smooth cubic Bézier curve defined by the previous control point, the current control point, and the current endpoint. - - ``: Specified as `arc [by | to] of [] [ | | rotate ]`. This command adds an [elliptical arc curve command](/en-US/docs/Web/SVG/Attribute/d#elliptical_arc_curve) to the list of shape commands. It draws an elliptical arc between a starting point and an ending point. The `by` or `to` keyword determines whether the ending point of the curve, specified by the first ``, is "relative" or "absolute", respectively. + Smooth curves ensure a continuous transition from the shape, while quadratic curves do not. Smooth quadratic curves maintain a seamless transition using a single control point, whereas smooth cubic curves provide a more refined transition using two control points. - The elliptical arc curve command defines two possible ellipses, which intersect both the starting and ending points, and each can be traced clockwise or counterclockwise, resulting in four possible arcs depending on the arc size, direction, and angle. The `of` keyword specifies the size of the ellipse from which the arc is taken. The first `` provides the horizontal radius of the ellipse and the second provides the vertical radius. If only one `` is provided, the value is used for both radii (the radius of a circle). The following parameters help to determine which of the four arcs are used: + ``: Specified as `arc [by | to] of [] [ | | rotate ]`. This command adds an [elliptical arc curve command](/en-US/docs/Web/SVG/Attribute/d#elliptical_arc_curve) to the list of shape commands. It draws an elliptical arc between a starting point and an ending point. The `by` or `to` keyword determines whether the ending point of the curve, specified by the first ``, is relative or absolute, respectively. - - ``: Indicates whether the desired arc is the one traced around the ellipse clockwise (`cw`) or counter-clockwise (`ccw`). If omitted, this defaults to `ccw`. - - ``: Indicates whether the desired arc is the larger (`large`) or smaller (`small`) of the two arcs. If omitted, this defaults to `small`. - - ``: Specifies the angle, in degrees, by which to rotate the ellipse relative to the x-axis. A positive angle rotates the ellipse clockwise, and a negative angle rotates it counter-clockwise. If omitted, this defaults to `0deg`. + The elliptical arc curve command defines two possible ellipses, which intersect both the starting and ending points, and each can be traced clockwise or counterclockwise, resulting in four possible arcs depending on the arc size, direction, and angle. The `of` keyword specifies the size of the ellipse from which the arc is taken: the first `` provides the horizontal radius of the ellipse, and the second `` provides the vertical radius. - > **Note:** If the starting and ending points of the arc lie on exactly opposite sides of the ellipse, there is only one possible ellipse and two possible arcs. In this case, `` specifies the arc to choose, and `` has no effect. + Specify the following parameters to choose which of the four arcs to use: - - `close`: Adds a [ClosePath command](/en-US/docs/Web/SVG/Attribute/d#closepath) to the list of shape commands, drawing a straight line from the current position (end of the last command) to the first point in the path defined in the `from ` parameter. To close the shape without drawing a line, include a `` with the originating coordinates before the close command. If the `close` command is immediately followed by a ``, it defines the starting point of the next shape or subpath. + - ``: Indicates whether the desired arc is the one traced around the ellipse clockwise (`cw`) or counterclockwise (`ccw`). If omitted, this defaults to `ccw`. + - ``: Indicates whether the desired arc is the larger (`large`) or smaller (`small`) of the two arcs. If omitted, this defaults to `small`. + - ``: Specifies the angle, in degrees, by which to rotate the ellipse relative to the x-axis. A positive angle rotates the ellipse clockwise, and a negative angle rotates it counterclockwise. If omitted, this defaults to `0deg`. + + Special situations are handled as follows: + + - If only one `` is provided, the same value is used for both the horizontal and vertical radii, effectively creating a circle. In this case, `` and `` have no affect. + - If either radius is zero, the command is equivalent to a `` to the ending point. + - If either radius is negative, its absolute value is used instead. + - If the horizontal and vertical radii don't describe an ellipse large enough to intersect both the starting point and ending points (after rotation by the specified ``), the radii are scaled up uniformly until the ellipse is just large enough to intersect both points. + - If the starting and ending points of the arc lie on exactly opposite sides of the ellipse, there is only one possible ellipse and two possible arcs. In this case, `` specifies the arc to choose, and `` has no effect. + + `close`: Adds a [ClosePath command](/en-US/docs/Web/SVG/Attribute/d#closepath) to the list of shape commands, drawing a straight line from the current position (end of the last command) to the first point in the path defined in the `from ` parameter. To close the shape without drawing a line, include a `` with the originating coordinates before the close command. If the `close` command is immediately followed by a ``, it defines the starting point of the next shape or subpath. ## Description @@ -129,7 +141,13 @@ However, `shape()` offers several advantages over using `path()`: ### Using `shape()` to define a path -This example demonstrates how the `shape()` function can be used in the {{cssxref("offset-path")}} property to define the shape of the path an element can follow. We're creating a curved path in this example. +This example demonstrates how the `shape()` function can be used in the {{cssxref("offset-path")}} property to define the shape of the path an element can follow. + +The first shape, `shape1`, follows a cubic Bézier curved path defined by the `curve to` command. Next, the `close` command draws a straight line from the curve's end point back to the initial point defined in the `from` command. Finally, `shape1` moves to its new position at `0px 150px` and then proceeds along a horizontal line. + +The second shape, `shape2`, initially follows a horizontal line, then moves back to its starting position at `50px 90px`. Next, it follows a vertical line before closing the path back to the initial point. + +Both shapes start with their original colors and gradually transition to `hotpink` by the end of the `move` animation, reverting to their initial color as the animation restarts. This cyclic color change provides you a visual cue about the animation's progression and restart. ```html hidden
@@ -159,6 +177,15 @@ body { border: 2px dotted green; margin: 20px; } + +@supports not (offset-path: shape(from 0 0, move to 0 0)) { + .container { + display: none; + } + body::after { + content: "Your browser doesn't support the `shape()` function yet."; + } +} ``` ```css @@ -169,19 +196,26 @@ body { position: absolute; text-align: center; line-height: 50px; - animation: move 5s infinite alternate ease-in-out; + animation: move 6s infinite linear; } .shape1 { - offset-path: shape(from 30% 60px, curve to 180px 180px via 90px 190px); + offset-path: shape( + from 30% 60px, + curve to 180px 180px via 90px 190px, + close, + move by 0px 150px, + hline by 40% + ); } .shape2 { offset-path: shape( - from 20px 20px, - move to 50px 90px, + from 50px 90px, hline to 8em, - vline by 20% + move to 50px 90px, + vline by 20%, + close ); } @@ -191,6 +225,7 @@ body { } 100% { offset-distance: 100%; + background-color: hotpink; } } ``` @@ -201,7 +236,7 @@ body { ### Using `shape()` to define the visible part of an element -This example demonstrates how the `shape()` function can be used in the {{cssxref("clip-path")}} property to create the shape of the clipping region. +This example demonstrates how the `shape()` function can be used in the {{cssxref("clip-path")}} property to create different shapes for the clipping region. The first shape (`shape1`) uses a triangle defined by straight lines. The second shape (`shape2`) includes curves and smooth transitions; it also illustrates the use of the `` after the `close` command, which adds a rectangular shape to the clipping region. ```html hidden
@@ -228,6 +263,15 @@ body { margin: 20px; background-color: lightgray; } + +@supports not (clip-path: shape(from 0 0, move to 0 0)) { + .container { + display: none; + } + body::after { + content: "Your browser doesn't support the `shape()` function yet."; + } +} ``` ```css @@ -240,19 +284,25 @@ body { line-height: 50px; } -/* Simple triangle */ +/* Triangular clipping region */ .shape1 { clip-path: shape(from 0% 0%, line to 100% 0%, line to 50% 100%, close); } -/* More complex shape with curves and smooth transitions */ +/* Clipping region with curves and smooth transitions and a box */ .shape2 { clip-path: shape( from 10px 10px, curve to 60px 20% via 40px 0, smooth to 90px 0, curve by -20px 60% via 10% 40px 20% 20px, - smooth by -40% -10px via -10px 70px + smooth by -40% -10px via -10px 70px, + close, + move to 100px 100px, + hline by 50px, + vline by 50px, + hline by -50px, + close ); } ```