From 8cd08162e592c1baf5d888f4c5a08a58360344b5 Mon Sep 17 00:00:00 2001 From: Dipika Bhattacharya Date: Mon, 27 May 2024 11:46:50 -0400 Subject: [PATCH] docs(css): FF126 - Support for `shape()` function (#33446) * wip * tests link updates * adds more inline links) * test links in shape page * adds reminaing links to path commands * updates other basic-shape pages * undo's the alphabetical ordering of shape functions * updates fill-rule example syntax * fixes shape() link * fixes broken link * partial review fixes * fixes anchor links * another attempt at anchor links * check if removing bezier works * adjusts interpolation text * undo the section title changes in d attribute * moves path under basic-shape * improves the basic-shape page * updates links to path() * missed this file in previous round * fixes review feedback * fixes review feedback in basic-shape/path * updates the note text for * Apply suggestions from code review Co-authored-by: Estelle Weyl * Apply suggestions from linter Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> * Apply suggestions from linter Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> * fixes shape and basic-shape feedback * element -> property * Apply suggestions from code review Co-authored-by: Estelle Weyl * Apply suggestions from code review * Apply suggestions from code review Co-authored-by: Estelle Weyl * Apply suggestions from code review Co-authored-by: Estelle Weyl --------- Co-authored-by: Estelle Weyl Co-authored-by: Estelle Weyl Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> --- files/en-us/_redirects.txt | 5 +- files/en-us/_wikihistory.json | 8 +- .../mozilla/firefox/releases/97/index.md | 2 +- .../en-us/web/css/basic-shape/circle/index.md | 2 +- files/en-us/web/css/basic-shape/index.md | 154 +++++----- .../web/css/{ => basic-shape}/path/index.md | 11 +- files/en-us/web/css/basic-shape/rect/index.md | 4 +- .../en-us/web/css/basic-shape/shape/index.md | 278 ++++++++++++++++++ files/en-us/web/css/basic-shape/xywh/index.md | 4 +- files/en-us/web/css/clip-path/index.md | 4 +- files/en-us/web/css/offset-path/index.md | 4 +- files/en-us/web/svg/attribute/d/index.md | 20 +- 12 files changed, 397 insertions(+), 99 deletions(-) rename files/en-us/web/css/{ => basic-shape}/path/index.md (74%) create mode 100644 files/en-us/web/css/basic-shape/shape/index.md diff --git a/files/en-us/_redirects.txt b/files/en-us/_redirects.txt index 695b775aa894b18..87ca4ed2b99ccb5 100644 --- a/files/en-us/_redirects.txt +++ b/files/en-us/_redirects.txt @@ -11615,7 +11615,7 @@ /en-US/docs/Web/CSS/filter-function/hue-rotate() /en-US/docs/Web/CSS/filter-function/hue-rotate /en-US/docs/Web/CSS/filter-function/invert() /en-US/docs/Web/CSS/filter-function/invert /en-US/docs/Web/CSS/filter-function/opacity() /en-US/docs/Web/CSS/filter-function/opacity -/en-US/docs/Web/CSS/filter-function/path() /en-US/docs/Web/CSS/path +/en-US/docs/Web/CSS/filter-function/path() /en-US/docs/Web/CSS/basic-shape/path /en-US/docs/Web/CSS/filter-function/saturate() /en-US/docs/Web/CSS/filter-function/saturate /en-US/docs/Web/CSS/filter-function/sepia() /en-US/docs/Web/CSS/filter-function/sepia /en-US/docs/Web/CSS/filter-function/url /en-US/docs/Web/CSS/url @@ -11681,7 +11681,8 @@ /en-US/docs/Web/CSS/pad /en-US/docs/Web/CSS/@counter-style/pad /en-US/docs/Web/CSS/paint /en-US/docs/Web/CSS/image/paint /en-US/docs/Web/CSS/paint() /en-US/docs/Web/CSS/image/paint -/en-US/docs/Web/CSS/path() /en-US/docs/Web/CSS/path +/en-US/docs/Web/CSS/path /en-US/docs/Web/CSS/basic-shape/path +/en-US/docs/Web/CSS/path() /en-US/docs/Web/CSS/basic-shape/path /en-US/docs/Web/CSS/prefix /en-US/docs/Web/CSS/@counter-style/prefix /en-US/docs/Web/CSS/radial-gradient /en-US/docs/Web/CSS/gradient/radial-gradient /en-US/docs/Web/CSS/radial-gradient() /en-US/docs/Web/CSS/gradient/radial-gradient diff --git a/files/en-us/_wikihistory.json b/files/en-us/_wikihistory.json index 67d704eeb8419bb..780268cadb3283a 100644 --- a/files/en-us/_wikihistory.json +++ b/files/en-us/_wikihistory.json @@ -80630,6 +80630,10 @@ "rebeccahauck" ] }, + "Web/CSS/basic-shape/path": { + "modified": "2020-12-11T11:12:50.012Z", + "contributors": ["chrisdavidmills", "rachelandrew"] + }, "Web/CSS/blend-mode": { "modified": "2020-10-15T21:29:47.283Z", "contributors": [ @@ -88381,10 +88385,6 @@ "AkashMishraa" ] }, - "Web/CSS/path": { - "modified": "2020-12-11T11:12:50.012Z", - "contributors": ["chrisdavidmills", "rachelandrew"] - }, "Web/CSS/percentage": { "modified": "2020-12-14T06:48:33.216Z", "contributors": [ diff --git a/files/en-us/mozilla/firefox/releases/97/index.md b/files/en-us/mozilla/firefox/releases/97/index.md index 25cbbcfc0092f8d..9713973437fedd2 100644 --- a/files/en-us/mozilla/firefox/releases/97/index.md +++ b/files/en-us/mozilla/firefox/releases/97/index.md @@ -37,7 +37,7 @@ No notable changes ### SVG - The SVG {{SVGAttr('d')}} attribute, used to define a path to be drawn, can now be used as a property in CSS. - It accepts the values [path()](/en-US/docs/Web/CSS/path) or `none`. (See [Firefox bug 1744599](https://bugzil.la/1744599) for details.) + It accepts the values [path()](/en-US/docs/Web/CSS/basic-shape/path) or `none`. (See [Firefox bug 1744599](https://bugzil.la/1744599) for details.) #### Removals diff --git a/files/en-us/web/css/basic-shape/circle/index.md b/files/en-us/web/css/basic-shape/circle/index.md index 88a6b181e55285a..2341af9440180eb 100644 --- a/files/en-us/web/css/basic-shape/circle/index.md +++ b/files/en-us/web/css/basic-shape/circle/index.md @@ -7,7 +7,7 @@ browser-compat: css.types.basic-shape.circle {{CSSRef}} -The **`circle()`** [CSS](/en-US/docs/Web/CSS) function is one of the {{cssxref("<basic-shape>")}} [data types](/en-US/docs/Web/CSS/CSS_Types). +The **`circle()`** CSS [function](/en-US/docs/Web/CSS/CSS_Functions) defines a circle using a radius and a position. It is one of the {{cssxref("<basic-shape>")}} data types. {{EmbedInteractiveExample("pages/css/function-circle.html")}} diff --git a/files/en-us/web/css/basic-shape/index.md b/files/en-us/web/css/basic-shape/index.md index 0a7ed11b3a9c7eb..ce6d383f4766a94 100644 --- a/files/en-us/web/css/basic-shape/index.md +++ b/files/en-us/web/css/basic-shape/index.md @@ -13,116 +13,119 @@ The **``** [CSS](/en-US/docs/Web/CSS) [data type](/en-US/docs/Web/C ## Syntax -The `` data type is defined with one of the basic shape functions listed below. +The `` data type is used to create basic shapes including rectangles by [container inset](#syntax_for_rectangles_by_container_insets), by [coordinate distance](#syntax_for_rectangles_by_distance), or by [set dimensions](#syntax_for_rectangles_with_dimensions), [circles](#syntax_for_circles), [ellipses](#syntax_for_ellipses), [polygons](#syntax_for_polygons), [paths](#syntax_for_paths), and [author created shapes](#syntax_for_shapes_experimental). These basic shapes are defined using one `` CSS functions, with each value requiring a parameter that follows the shape's function-specific syntax. -When creating a shape, the reference box is defined by each property that uses `` values. The coordinate system for the shape has its origin at the top-left corner of the reference box, with the x-axis running to the right and the y-axis running downwards. All the lengths expressed in percentages are resolved from the used dimensions of the reference box. +### Common parameters -The default reference box is the `margin-box`, as demonstrated in the below image which shows a circle created using `shape-outside: circle(50%)`. The shape is being defined with reference to the margin box. +The parameters common across the syntax of some basic shape functions include: -![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) +- `round <'border-radius'>` -### Shape functions + - : Defines rounded corners for [rectangles by container insets](#syntax_for_rectangles_by_container_insets), [rectangles by distance](#syntax_for_rectangles_by_distance), and [rectangles with dimensions](#syntax_for_rectangles_with_dimensions) using the same syntax as the CSS [`border-radius`](/en-US/docs/Web/CSS/border-radius) shorthand property. -The following shapes are supported. All `` values use functional notation and are defined here using the [value definition syntax](/en-US/docs/Web/CSS/Value_definition_syntax). +- `` -- `{{cssxref("basic-shape/inset","inset()")}}` + - : Defines the radius for a [circle](#syntax_for_circles) or an [ellipse](#syntax_for_ellipses). Valid values include {{cssxref("length")}}, {{cssxref("percentage")}}, `closest-side` (the default), and `farthest-side`. Negative values are invalid. - - : Defines an inset rectangle. + The `closest-side` keyword value uses the length from the center of the shape to the closest side of the reference box to create the radius length. The `farthest-side` keyword value uses the length from the center of the shape to the farthest side of the reference box. - ```css - inset( {1,4} [ round <`border-radius`> ]? ) - ``` +- `` - When all of the first four arguments are supplied, they represent the top, right, bottom and left offsets from the reference box inward that define the position of the edges of the inset rectangle. These arguments follow the syntax of the {{cssxref("margin")}} shorthand, which lets you set all four insets with one, two, three, or four values. + - : Defines the center [``](/en-US/docs/Web/CSS/position_value) of a [circle](#syntax_for_circles) or an [ellipse](#syntax_for_ellipses). It defaults to `center` if omitted. - The optional `round <'border-radius'>` parameter defines rounded corners for the inset rectangle using the same syntax as the CSS [`border-radius`](/en-US/docs/Web/CSS/border-radius) shorthand property. +- `` - A pair of insets in either dimension that add up to more than the used dimension (such as left and right insets of 75% apiece) define a shape enclosing no area. For this specification, this results in an empty float area. + - : Sets the {{SVGAttr("fill-rule")}} that is used to determine how the interior of the shape defined by the basic shapes [polygon](#syntax_for_polygons), [path](#syntax_for_paths), and [shape](#syntax_for_shapes_experimental) is to be filled. Possible values are `nonzero` (the default) and `evenodd`. -- `{{cssxref("basic-shape/rect","rect()")}}` + > **Note:** `` is not supported in {{cssxref("offset-path")}} and using it invalidates the property. - - : Defines a rectangle using the specified distances from the top and left edges of the reference box. +### Syntax for rectangles by container insets - ```css - rect( [ | auto ]{4} [ round <`border-radius`> ]? ) - ``` +The {{cssxref("basic-shape/inset","inset()")}} function creates an inset rectangle, with its size defined by the offset distance of each of the four sides of its container and, optionally, rounded corners. - You specify four values to create the rectangle. Each of the four values is either a ``, a ``, or the keyword `auto`. When using the `rect()` function, you do not define the width and height of the rectangle. The rectangle's dimensions depend on the size of the reference box and the offset values. +```plain +inset( {1,4} [ round <`border-radius`> ]? ) +``` - The optional `round <'border-radius'>` parameter defines rounded corners for the inset rectangle using the same syntax as the CSS [`border-radius`](/en-US/docs/Web/CSS/border-radius) shorthand property. +When all of the first four arguments are supplied, they represent the top, right, bottom and left offsets from the reference box inward that define the position of the edges of the inset rectangle. These arguments follow the syntax of the {{cssxref("margin")}} shorthand, which lets you set all four insets with one, two, three, or four values. -- `{{cssxref("basic-shape/xywh","xywh()")}}` +If a pair of insets for a dimension adds up to more than 100% of that dimension, both values are proportionally reduced so their sum equals 100%. For example, the value `inset(90% 10% 60% 10%)` has a top inset of `90%` and a bottom inset of `60%`. These values are reduced proportionally to `inset(60% 10% 40% 10%)`. Shapes such as this, that enclose no area and have no {{cssxref("shape-margin")}}, have no effect on wrapping - - : Defines a rectangle using the specified distances from the top and left edges of the reference box and the specified width and height of the rectangle. +### Syntax for rectangles by distance - ```css - xywh( {2} {2} [ round <`border-radius`> ]? ) - ``` +The {{cssxref("basic-shape/rect","rect()")}} function defines a rectangle using the specified distances from the top and left edges of the reference box, with optional rounded corners. - The optional `round <'border-radius'>` parameter defines rounded corners for the inset rectangle using the [`border-radius`](/en-US/docs/Web/CSS/border-radius) shorthand syntax. +```plain +rect( [ | auto ]{4} [ round <`border-radius`> ]? ) +``` -- `{{cssxref("basic-shape/circle","circle()")}}` +When using the `rect()` function, you do not define the width and height of the rectangle. Instead, you specify four values to create the rectangle, with its dimensions determined by the size of the reference box and the four offset values. Each value can be either a {{cssxref("length")}}, a {{cssxref("percentage")}}, or the keyword `auto`. The `auto` keyword is interpreted as `0%` for the top and left values and as `100%` for the bottom and right values. - - : Defines a circle using a radius and a position. +### Syntax for rectangles with dimensions - ```css - circle( ? [ at ]? ) - ``` +The {{cssxref("basic-shape/xywh","xywh()")}} function defines a rectangle located at the specified distances from the left (`x`) and top (`y`) edges of the reference box and sized by the specified width (`w`) and height (`h`) of the rectangle, in that order, with optional rounded corners. - The `` argument represents _r_, the radius of the circle. Negative values are invalid. A percentage value here is resolved from the used width and height of the reference box as `sqrt(width^2+height^2)/sqrt(2)`. +```plain +xywh( {2} {2} [ round <`border-radius`> ]? ) +``` - The {{cssxref("<position>")}} argument defines the center of the circle. This defaults to center if omitted. +### Syntax for circles -- `{{cssxref("basic-shape/ellipse","ellipse()")}}` +The {{cssxref("basic-shape/circle","circle()")}} function defines a circle using a radius and a position. - - : Defines an ellipse using two radii and a position. +```plain +circle( ? [ at ]? ) +``` - ```css - ellipse( [ {2} ]? [ at ]? ) - ``` +The `` argument represents the radius of the circle defined as either a {{cssxref("length")}} or a {{cssxref("percentage")}}. A percentage value here is resolved from the used width and height of the reference box as `sqrt(width^2+height^2)/sqrt(2)`. If omitted, the radius is defined by `closest-side`. - The `` arguments represent rx and ry, the x-axis and y-axis radii of the ellipse, in that order. Negative values for either radius are invalid. Percentage values here are resolved against the used width (for the rx value) and the used height (for the ry value) of the reference box. +### Syntax for ellipses - The position argument defines the center of the ellipse. This defaults to center if omitted. +The {{cssxref("basic-shape/ellipse","ellipse()")}} function defines an ellipse using two radii and a position. -- `{{cssxref("basic-shape/polygon","polygon()")}}` +```plain +ellipse( [ {2} ]? [ at ]? ) +``` - - : Defines a polygon using an SVG {{SVGAttr("fill-rule")}} and a set of vertices. +The `` arguments represent _rx_ and _ry_, the x-axis and y-axis radii of the ellipse, in that order. These values are specified as either a {{cssxref("length")}} or a {{cssxref("percentage")}}. Percentage values here are resolved against the used width (for the rx value) and the used height (for the ry value) of the reference box. If only one radius value is provided, the `ellipse()` shape function is invalid. If no value is provided, `50% 50%` is used. - ```css - polygon( ? [ ]# ) - ``` +### Syntax for polygons - `` represents the {{SVGAttr("fill-rule")}} used to determine the interior of the polygon. Possible values are `nonzero` and `evenodd`. Default value when omitted is `nonzero`. +The {{cssxref("basic-shape/polygon","polygon()")}} function defines a polygon using an SVG {{SVGAttr("fill-rule")}} and a set of coordinates. - Each pair argument in the list represents _xi_ and _yi_ - the x and y axis coordinates of the vertex of the polygon at position i. +```plain +polygon( <`fill-rule`>?, [ ]# ) +``` -- `{{cssxref("path","path()")}}` +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_. - - : Defines a shape using an SVG {{SVGAttr("fill-rule")}} and an SVG [path definition](/en-US/docs/Web/SVG/Attribute/d). +### Syntax for paths - ```css - path( [ , ]? ) - ``` +The {{cssxref("basic-shape/path","path()")}} function defines a shape using an SVG {{SVGAttr("fill-rule")}} and an SVG [path definition](/en-US/docs/Web/SVG/Attribute/d). - The optional `` represents the {{SVGAttr("fill-rule")}} used to determine the interior of the path. Possible values are `nonzero` and `evenodd`. Default value when omitted is `nonzero`. +```plain +path( <`fill-rule`>?, ]? ) +``` - The required \ is an [SVG Path](/en-US/docs/Web/SVG/Attribute/d) string encompassed in quotes +The required `` is an [SVG Path](/en-US/docs/Web/SVG/Attribute/d) as a quoted string. -The arguments not defined above are defined as follows: +### Syntax for shapes {{Experimental_Inline}} -```css - = | - = | | closest-side | farthest-side +The {{cssxref("basic-shape/shape","shape()")}} function defines a shape using an initial starting point and a series of shape commands. + +```plain +shape( ? from , # ) ``` -Defines a radius for a circle or ellipse. If omitted it defaults to `closest-side`. +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). + +## Description -`closest-side` uses the length from the center of the shape to the closest side of the reference box. For circles, this is the closest side in any dimension. For ellipses, this is the closest side in the radius dimension. +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. -`farthest-side` uses the length from the center of the shape to the farthest side of the reference box. For circles, this is the farthest side in any dimension. For ellipses, this is the farthest side in the radius dimension. +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. -## Description +![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 @@ -134,14 +137,25 @@ The values in a `` function are computed as specified, with these e ### Interpolation of basic shapes -When animating between one `` and another, the rules below are applied. The values in the shape functions {{Glossary("interpolation", "interpolate")}} as a simple list. The list values interpolate as {{cssxref("<length>")}}, {{cssxref("<percentage>")}}, or {{cssxref("calc", "calc()")}} where possible. If list values are not one of those types but are identical, those values do interpolate. +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. + +- **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`). + +- **Both shapes are of type `inset()`**: Interpolation is applied between each corresponding value. + +- **Both shapes are of type `polygon()`**: Interpolation is applied between each corresponding value if they use the same `` and have the same number of comma-separated coordinate pairs. + +- **Both shapes are of type `path()`**: Interpolation is applied to each parameter as a {{cssxref("<number>")}} if the path strings in both the shapes match the number, type, and sequence of [path data commands](/en-US/docs/Web/SVG/Attribute/d#path_commands). + +- **Both shapes are of type `shape()`**: Interpolation is applied between each corresponding value if they have the identical command keyword and use the same `` keyword. If `shape()` is used in the {{cssxref("clip-path")}} property, the two shapes interpolate if they also have the same ``. + + - If they use the `` or the ``, the number of control points must match for interpolation. + + - If they use the `` with different `` directions, the interpolated result goes clockwise (`cw`). If they use different `` keywords, the size is interpolated using the `large` value. + +- **One shape is of type `path()` and the other is of type `shape()`**: Interpolation is applied between each corresponding value if the list of path data commands is identical in number as well as sequence. The interpolated shape is a `shape()` function, maintaining the same list of path data commands. -- Both shapes must use the same reference box. -- If both shapes are the same type, that type is `ellipse()` or `circle()`, and none of the radii use the `closest-side` or `farthest-side` keywords, interpolate between each value in the shape functions. -- If both shapes are of type `inset()`, interpolate between each value in the shape functions. -- If both shapes are of type `polygon()`, both polygons have the same number of vertices, and use the same ``, interpolate between each value in the shape functions. -- If both shapes are of type `path()`, both paths strings have the same number and types of path data commands in the same order, interpolate each path data command as real numbers. -- In all other cases no interpolation occurs. +In all other cases, no interpolation occurs and the animation is discrete. ## Examples diff --git a/files/en-us/web/css/path/index.md b/files/en-us/web/css/basic-shape/path/index.md similarity index 74% rename from files/en-us/web/css/path/index.md rename to files/en-us/web/css/basic-shape/path/index.md index 8ab20757a2ab1d8..a29364e7387a198 100644 --- a/files/en-us/web/css/path/index.md +++ b/files/en-us/web/css/basic-shape/path/index.md @@ -1,13 +1,13 @@ --- title: path() -slug: Web/CSS/path +slug: Web/CSS/basic-shape/path page-type: css-function browser-compat: css.types.basic-shape.path --- {{CSSRef}} -The **`path()`** [CSS](/en-US/docs/Web/CSS) [function](/en-US/docs/Web/CSS/CSS_Functions) accepts an SVG path string, and is used in [CSS Shapes](/en-US/docs/Web/CSS/CSS_shapes) and CSS Motion Path to enable a shape to be drawn. +The **`path()`** [CSS](/en-US/docs/Web/CSS) [function](/en-US/docs/Web/CSS/CSS_Functions) accepts an [SVG path](/en-US/docs/Web/SVG/Element/path) string, and is used in the [CSS shapes](/en-US/docs/Web/CSS/CSS_shapes) and [CSS motion path](/en-US/docs/Web/CSS/CSS_motion_path) modules to enable a shape to be drawn. The `path()` function is a {{cssxref("<basic-shape>")}} data type value. It can be used in the CSS [`offset-path`](/en-US/docs/Web/CSS/offset-path) and [`clip-path`](/en-US/docs/Web/CSS/clip-path) properties and in the SVG [`d`](/en-US/docs/Web/SVG/Attribute/d) attribute. {{EmbedInteractiveExample("pages/css/function-path.html")}} @@ -22,13 +22,16 @@ path() When used in {{cssxref("clip-path")}}: ```css -path([<'fill-rule'>,]?) +path( [,]? ) ``` ### Parameters - [``](/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 specifies the filling rule. + + - : 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. + - {{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/rect/index.md b/files/en-us/web/css/basic-shape/rect/index.md index e6475e32e51d4d6..be5c80d177cb892 100644 --- a/files/en-us/web/css/basic-shape/rect/index.md +++ b/files/en-us/web/css/basic-shape/rect/index.md @@ -111,8 +111,8 @@ In this example, the {{cssxref("offset-path")}} property uses the `rect()` funct ## See also -- [`inset()`](/en-US/docs/Web/CSS/basic-shape#inset) function -- [`xywh()`](/en-US/docs/Web/CSS/basic-shape#xywh) function +- {{cssxref("basic-shape/inset","inset()")}} function +- {{cssxref("basic-shape/xywh","xywh()")}} function - {{cssxref("clip-path")}} property - {{cssxref("offset-path")}} property - {{cssxref("<basic-shape>")}} data type diff --git a/files/en-us/web/css/basic-shape/shape/index.md b/files/en-us/web/css/basic-shape/shape/index.md new file mode 100644 index 000000000000000..364dde4aa523cd0 --- /dev/null +++ b/files/en-us/web/css/basic-shape/shape/index.md @@ -0,0 +1,278 @@ +--- +title: shape() +slug: Web/CSS/basic-shape/shape +page-type: css-function +browser-compat: css.types.basic-shape.shape +--- + +{{CSSRef}} + +The **`shape()`** [CSS function](/en-US/docs/Web/CSS/CSS_Functions) is used to define a shape for the {{cssxref("clip-path")}} and {{cssxref("offset-path")}} properties. It combines an initial starting point with a series of shape commands that define the path of the shape. The `shape()` function is a member of the {{cssxref("<basic-shape>")}} data type. + +## Syntax + +```css +/* */ +clip-path: shape(nonzero from 0 0, line to 10px 10px); + +/* , , and close */ +offset-path: shape(from 10px 10px, move by 10px 5px, line by 20px 40%, close); + +/* */ +offset-path: shape(from 10px 10px, hline by 50px, vline to 5rem); + +/* */ +offset-path: shape(from 10px 10px, curve to 80px 80px via 160px 1px 20% 16px); + +/* */ +offset-path: shape(from 10px 10px, smooth to 100px 50pt); + +/* */ +offset-path: shape( + from 5% 0.5rem, + arc to 80px 1pt of 10% ccw large rotate 25deg +); + +/* Using a CSS math function */ +offset-path: shape( + from 5px -5%, + hline to 50px, + vline by calc(0% + 160px), + hline by 70.5px, + close, + vline by 60px +); + +clip-path: shape( + nonzero 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 +); +``` + +### Parameters + +- [``](/en-US/docs/Web/SVG/Attribute/fill-rule) {{optional_inline}} + + - : Specifies how overlapping regions of a shape should 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. + + > **Note:** `` is not supported in {{cssxref("offset-path")}} and using it invalidates the property. + +- `from ` + + - : Defines the starting point of the first `` as a pair of coordinates that are measured from the top-left corner of the [reference box](/en-US/docs/Web/CSS/CSS_shapes/Basic_shapes#the_reference_box). The coordinates are specified as space-separated ` ` {{cssxref("<length-percentage>")}} values representing the left offset and top offset, respectively. Percentage values are relative to the width and height of the element's reference box, respectively. Add a comma after this parameter. + +- `` + + - : Specifies a list of one or more comma-separated commands that define the shape, using syntax similar to [SVG path commands](/en-US/docs/Web/SVG/Attribute/d#path_commands). Commands include ``, ``, ``, ``, ``, ``, and `close`. Each command's starting point is the previous command's ending point, with the first point of the shape defined by the [`from `](#from_coordinate-pair) parameter. + + 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). + + `to`: Indicates that the `` is relative to the top-left corner of the reference box ("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: + + - ``: 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 `[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. + + 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). + + - ``: 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. + + - ``: 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. + + 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: + + - ``: 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`. + + > **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. + + - `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 + +The `shape()` function allows you to define complex shapes. It is similar to the {{cssxref("basic-shape/path","path()")}} shape function in several ways: + +- The `` parameter in the `shape()` function works exactly like the same parameter in the `path()` function. +- The `shape()` function requires specifying one or more ``s, where each command uses an underlying [path command](/en-US/docs/Web/SVG/Attribute/d#path_commands), such as [MoveTo](/en-US/docs/Web/SVG/Attribute/d#moveto_path_commands), [LineTo](/en-US/docs/Web/SVG/Attribute/d#lineto_path_commands), and [ClosePath](/en-US/docs/Web/SVG/Attribute/d#closepath). + +However, `shape()` offers several advantages over using `path()`: + +- `shape()` uses standard CSS syntax, making it easier to create and modify shapes directly in your stylesheet. In comparison, `path()` uses the [SVG path](/en-US/docs/Web/SVG/Element/path) syntax, which is less intuitive for those not familiar with SVG. +- `shape()` supports a variety of CSS units, including percentages, `rem`, and `em`. `path()`, on the other hand, defines shapes as a single string and limits units to `px`. +- `shape()` also allows the use of CSS math functions, like {{cssxref("calc")}}, {{cssxref("max")}}, and {{cssxref("abs")}}, providing more versatility when defining shapes. + +## Formal syntax + +{{csssyntax}} + +## Examples + +### 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. + +```html hidden +
+ Using <curve-command> +
>>
+
+ +
+ Using <move-command> and + <hvline-command> +
>>
+
+``` + +```css hidden +body { + align-items: center; + justify-content: center; + display: flex; +} + +.container { + position: relative; + display: inline-block; + width: 250px; + height: 250px; + border: 2px dotted green; + margin: 20px; +} +``` + +```css +.shape { + width: 50px; + height: 50px; + background: #2bc4a2; + position: absolute; + text-align: center; + line-height: 50px; + animation: move 5s infinite alternate ease-in-out; +} + +.shape1 { + offset-path: shape(from 30% 60px, curve to 180px 180px via 90px 190px); +} + +.shape2 { + offset-path: shape( + from 20px 20px, + move to 50px 90px, + hline to 8em, + vline by 20% + ); +} + +@keyframes move { + 0% { + offset-distance: 0%; + } + 100% { + offset-distance: 100%; + } +} +``` + +#### Result + +{{EmbedLiveSample('Using shape() to define a path', '100%', 300)}} + +### 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. + +```html hidden +
+
+
+ +
+
+
+``` + +```css hidden +body { + align-items: center; + justify-content: center; + display: flex; +} + +.container { + position: relative; + display: inline-block; + width: 200px; + height: 200px; + margin: 20px; + background-color: lightgray; +} +``` + +```css +.shape { + width: 100%; + height: 100%; + background: #2bc4a2; + position: absolute; + text-align: center; + line-height: 50px; +} + +/* Simple triangle */ +.shape1 { + clip-path: shape(from 0% 0%, line to 100% 0%, line to 50% 100%, close); +} + +/* More complex shape with curves and smooth transitions */ +.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 + ); +} +``` + +#### Result + +{{EmbedLiveSample('Using shape() to define the visible part of an element', '100%', 300)}} + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- {{cssxref("clip-path")}} +- {{cssxref("offset-path")}} +- [CSS shapes](/en-US/docs/Web/CSS/CSS_shapes) module +- [Overview of shapes](/en-US/docs/Web/CSS/CSS_shapes/Overview_of_shapes) guide +- [Basic shapes](/en-US/docs/Web/CSS/CSS_shapes/Basic_shapes) guide diff --git a/files/en-us/web/css/basic-shape/xywh/index.md b/files/en-us/web/css/basic-shape/xywh/index.md index bf565774e0c44d0..c380a4e21e278a5 100644 --- a/files/en-us/web/css/basic-shape/xywh/index.md +++ b/files/en-us/web/css/basic-shape/xywh/index.md @@ -96,8 +96,8 @@ In the example below, the {{cssxref("offset-path")}} property uses the `xywh()` ## See also -- [`inset()`](/en-US/docs/Web/CSS/basic-shape#inset) function -- [`rect()`](/en-US/docs/Web/CSS/basic-shape#rect) function +- {{cssxref("basic-shape/inset","inset()")}} function +- {{cssxref("basic-shape/rect","rect()")}} function - {{cssxref("clip-path")}} property - {{cssxref("offset-path")}} property - {{cssxref("<basic-shape>")}} data type diff --git a/files/en-us/web/css/clip-path/index.md b/files/en-us/web/css/clip-path/index.md index 36b2cafcfb64175..b2a8920390e6493 100644 --- a/files/en-us/web/css/clip-path/index.md +++ b/files/en-us/web/css/clip-path/index.md @@ -69,10 +69,12 @@ The `clip-path` property is specified as one or a combination of the values list - : Defines an ellipse using two radii and a position. - {{cssxref("basic-shape/polygon","polygon()")}} - : Defines a polygon using an SVG filling rule and a set of vertices. - - {{cssxref("path","path()")}} + - {{cssxref("basic-shape/path","path()")}} - : Defines a shape using an optional SVG filling rule and an SVG path definition. - {{cssxref("basic-shape/rect","rect()")}} - : Defines a rectangle using the specified distances from the edges of the reference box. + - {{cssxref("basic-shape/shape","shape()")}} {{Experimental_Inline}} + - : Defines a shape using an optional SVG filling rule and shape commands for lines, curves, and arcs. - {{cssxref("basic-shape/xywh","xywh()")}} - : Defines a rectangle using the specified distances from the top and left edges of the reference box and the specified width and height of the rectangle. diff --git a/files/en-us/web/css/offset-path/index.md b/files/en-us/web/css/offset-path/index.md index 43902b76ffa450b..6ac64360b933a79 100644 --- a/files/en-us/web/css/offset-path/index.md +++ b/files/en-us/web/css/offset-path/index.md @@ -74,7 +74,7 @@ The `offset-path` property takes as its value an `` value, a [`` is an `ellipse()` function, then the path is the outline of the ellipse, starting at the rightmost point of the ellipse, proceeding clockwise through a full rotation. For `ellipse()` and `circle()`, which accept the `at ` parameter, if the `` is omitted, the position defaults to `center` unless the element has an {{cssxref("offset-position")}} specified. In this case, the `offset-position` value is used for the `at ` parameter. + - : Specifies the offset path as the equivalent path of a {{cssxref("basic-shape", "CSS basic shape function")}}, such as {{cssxref("basic-shape/circle","circle()")}}, {{cssxref("basic-shape/ellipse","ellipse()")}}, {{cssxref("basic-shape/inset","inset()")}}, {{cssxref("basic-shape/path","path()")}}, {{cssxref("basic-shape/polygon","polygon()")}}, {{cssxref("basic-shape/rect","rect()")}}, or {{cssxref("basic-shape/xywh","xywh()")}}. For example, if the `` is an `ellipse()` function, then the path is the outline of the ellipse, starting at the rightmost point of the ellipse, proceeding clockwise through a full rotation. For `ellipse()` and `circle()`, which accept the `at ` parameter, if the `` is omitted, the position defaults to `center` unless the element has an {{cssxref("offset-position")}} specified. In this case, the `offset-position` value is used for the `at ` parameter. More complex shapes can be defined using the {{cssxref("basic-shape/shape","shape()")}} function. - [``](/en-US/docs/Web/CSS/box-edge#values) @@ -296,7 +296,7 @@ The SVG rectangle that defines the path shape is shown here only to visually dem - {{cssxref("offset-distance")}} - {{cssxref("offset-rotate")}} - [SVG \](/en-US/docs/Web/SVG/Tutorial/Paths) -- {{cssxref("path","path()")}} +- {{cssxref("basic-shape/path","path()")}} - Other demos: - [Examples using various shapes values](https://codepen.io/team/css-tricks/pen/WZdKMq) on Codepen by CSS-Tricks - [Moving a triangle along a curved path](https://codepen.io/ericwilligers/pen/jMbJPp) on Codepen by Eric Willigers diff --git a/files/en-us/web/svg/attribute/d/index.md b/files/en-us/web/svg/attribute/d/index.md index 80c3539b30df02d..ae44bf9d3a75cd1 100644 --- a/files/en-us/web/svg/attribute/d/index.md +++ b/files/en-us/web/svg/attribute/d/index.md @@ -119,7 +119,7 @@ For {{SVGElement('missing-glyph')}}, `d` is a string containing a series of path ## Using d as a CSS property `d` is a presentation attribute, and hence can be also be modified using CSS. -The property takes either [path()](/en-US/docs/Web/CSS/path) or `none`. +The property takes either [path()](/en-US/docs/Web/CSS/basic-shape/path) or `none`. The example below shows how you might apply a new path on hover over an element. The new path is the same as the old one, but adds a line across the heart. @@ -161,12 +161,12 @@ Path commands are instructions that define a path to be drawn. Each command is c SVG defines 6 types of path commands, for a total of 20 commands: -- MoveTo: `M`, `m` -- LineTo: `L`, `l`, `H`, `h`, `V`, `v` -- Cubic Bézier Curve: `C`, `c`, `S`, `s` -- Quadratic Bézier Curve: `Q`, `q`, `T`, `t` -- Elliptical Arc Curve: `A`, `a` -- ClosePath: `Z`, `z` +- [MoveTo](#moveto_path_commands): `M`, `m` +- [LineTo](#lineto_path_commands): `L`, `l`, `H`, `h`, `V`, `v` +- [Cubic Bézier curve](#cubic_bézier_curve): `C`, `c`, `S`, `s` +- [Quadratic Bézier curve](#quadratic_bézier_curve): `Q`, `q`, `T`, `t` +- [Elliptical arc curve](#elliptical_arc_curve): `A`, `a` +- [ClosePath](#closepath): `Z`, `z` > **Note:** Commands are _case-sensitive_. An upper-case command specifies absolute coordinates, while a lower-case command specifies coordinates relative to the current position. @@ -456,7 +456,7 @@ svg { {{EmbedLiveSample('LineTo_path_commands', '100%', 200)}} -### Cubic Bézier Curve +### Cubic Bézier curve _Cubic [Bézier curves](/en-US/docs/Glossary/Bezier_curve)_ are smooth curve definitions using four points: @@ -684,7 +684,7 @@ svg { {{EmbedLiveSample('Cubic_Bézier_Curve', '100%', 200)}} -### Quadratic Bézier Curve +### Quadratic Bézier curve _Quadratic [Bézier curves](/en-US/docs/Glossary/Bezier_curve)_ are smooth curve definitions using three points: @@ -909,7 +909,7 @@ svg { {{EmbedLiveSample('Quadratic_Bézier_Curve', '100%', 200)}} -### Elliptical Arc Curve +### Elliptical arc curve _Elliptical arc curves_ are curves defined as a portion of an ellipse. It is sometimes easier to draw highly regular curves with an elliptical arc than with a Bézier curve.