Skip to content

Commit b0e7535

Browse files
SebastianZSebastianZ
committed
Added box-shadow-* longhand properties
1 parent a4d0180 commit b0e7535

File tree

1 file changed

+373
-0
lines changed

1 file changed

+373
-0
lines changed

‎css-backgrounds-4/Overview.bs‎

Lines changed: 373 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -690,6 +690,379 @@ The 'border-clip' properties</h3>
690690
<p>The fragments are shown in red for illustrative purposes; they should be black in compliant UAs.
691691
</div>
692692

693+
<h2 id="misc">Drop Shadows</h2>
694+
695+
<h3 id="box-shadow-color">Coloring shadows: the 'box-shadow-color' property</h3>
696+
697+
<pre class="propdef">
698+
Name: box-shadow-color
699+
Value: <<color>>#
700+
Initial: currentcolor
701+
Applies to: all elements
702+
Inherited: no
703+
Percentages: N/A
704+
Computed value: list, each item a computed color
705+
Animatable: by computed value
706+
</pre>
707+
708+
<p>The 'box-shadow-color' property defines one or more drop shadow colors.
709+
The property accepts a comma-separated list of shadow colors.
710+
711+
<p>See the section <a href="#shadow-layers">“Layering, Layout, and
712+
Other Details”</a> for how 'box-shadow-color' interacts with other
713+
comma-separated drop shadow properties to form each drop shadow
714+
layer.
715+
716+
<h3 id="box-shadow-offset">Offsetting shadows: the 'box-shadow-offset' property</h3>
717+
718+
<pre class="propdef">
719+
Name: box-shadow-offset
720+
Value: <<length>>{2}#
721+
Initial: 0 0
722+
Applies to: all elements
723+
Inherited: no
724+
Percentages: N/A
725+
Computed value: list, each item a pair of offsets (horizontal and vertical) from the element‘s box
726+
Animatable: by computed value
727+
</pre>
728+
729+
<p>The 'box-shadow-offset' property defines one or more drop shadow offsets.
730+
The property accepts a comma-separated list of horizontal and vertical offset pairs,
731+
where both values are described as <<length>> values.
732+
733+
<dl>
734+
<dt><dfn id="shadow-offset-x">1st <<length>></dfn>
735+
<dd>
736+
Specifies the <dfn>horizontal offset</dfn> of the shadow.
737+
A positive value draws a shadow that is offset to the right of the box,
738+
a negative length to the left.
739+
740+
<dt><dfn id="shadow-offset-y">2nd <<length>></dfn>
741+
<dd>
742+
Specifies the <dfn>vertical offset</dfn> of the shadow.
743+
A positive value offsets the shadow down, a negative one up.
744+
</dl>
745+
746+
<p>See the section <a href="#shadow-layers">“Layering, Layout, and
747+
Other Details”</a> for how 'box-shadow-offset' interacts with other
748+
comma-separated drop shadow properties to form each drop shadow
749+
layer.
750+
751+
<h3 id="box-shadow-blur">Blurring shadows: the 'box-shadow-blur' property</h3>
752+
753+
<pre class="propdef">
754+
Name: box-shadow-blur
755+
Value: <<length [0,&infin;]>>#
756+
Initial: 0
757+
Applies to: all elements
758+
Inherited: no
759+
Percentages: N/A
760+
Computed value: list, each item a <<length>>
761+
Animatable: by computed value
762+
</pre>
763+
764+
<p>The 'box-shadow-blur' property defines one or more blur radii for drop shadows.
765+
The property accepts a comma-separated list of <<length>> values.
766+
767+
<p>Negative values are invalid.
768+
If the blur value is zero, the shadow’s edge is sharp.
769+
Otherwise, the larger the value, the more the shadow’s edge is blurred.
770+
See <a href="#shadow-blur">Shadow Blurring</a>, below.
771+
772+
<p>See the section <a href="#shadow-layers">“Layering, Layout, and
773+
Other Details”</a> for how 'box-shadow-blur' interacts with other
774+
comma-separated drop shadow properties to form each drop shadow
775+
layer.
776+
777+
<h3 id="box-shadow-spread">Spreading shadows: the 'box-shadow-spread' property</h3>
778+
779+
<pre class="propdef">
780+
Name: box-shadow-spread
781+
Value: <<length>>#
782+
Initial: 0
783+
Applies to: all elements
784+
Inherited: no
785+
Percentages: N/A
786+
Computed value: list, each item a <<length>>
787+
Animatable: by computed value
788+
</pre>
789+
790+
<p>The 'box-shadow-spread' property defines one or more spread distances for drop shadows.
791+
The property accepts a comma-separated list of <<length>> values.
792+
793+
<p>Positive values cause the shadow to expand in all directions by the specified radius.
794+
Negative values cause the shadow to contract.
795+
See <a href="#shadow-shape">Shadow Shape</a>, below.
796+
<p class="note">Note that for inner shadows,
797+
expanding the shadow (creating more shadow area)
798+
means contracting the shadow’s perimeter shape.
799+
800+
<p>See the section <a href="#shadow-layers">“Layering, Layout, and
801+
Other Details”</a> for how 'box-shadow-spread' interacts with other
802+
comma-separated drop shadow properties to form each drop shadow
803+
layer.
804+
805+
<h3 id="box-shadow-position">Spreading shadows: the 'box-shadow-position' property</h3>
806+
807+
<pre class="propdef">
808+
Name: box-shadow-position
809+
Value: [ outset | inset ]#
810+
Initial: outset
811+
Applies to: all elements
812+
Inherited: no
813+
Percentages: N/A
814+
Computed value: list, each item one of the keywords
815+
Animatable: by computed value
816+
</pre>
817+
818+
<p>The 'box-shadow-position' property defines one or more drop shadow positions.
819+
The property accepts a comma-separated list of 'outset' and 'inset' keywords.
820+
821+
<dl dfn-type=value dfn-for=box-shadow-position>
822+
<dt><dfn>outset</dfn>
823+
<dd>
824+
Causes the drop shadow to be an <dfn local-lt="outer shadow">outer box-shadow</dfn>.
825+
That means, one that shadows the box onto the canvas, as if it were lifted above the canvas.
826+
827+
<dt><dfn>inset</dfn>
828+
<dd>
829+
Causes the drop shadow to be an <dfn local-lt="inner shadow">inner box-shadow</dfn>.
830+
That means, one that shadows the canvas onto the box, as if the box were cut out
831+
of the canvas and shifted behind it.
832+
</dl>
833+
834+
<p>See the section <a href="#shadow-layers">“Layering, Layout, and
835+
Other Details”</a> for how 'box-shadow-position' interacts with other
836+
comma-separated drop shadow properties to form each drop shadow
837+
layer.
838+
839+
<h3 id="box-shadow" oldids="the-box-shadow">Drop Shadows Shorthand: the 'box-shadow' property</h3>
840+
841+
<pre class="propdef">
842+
Name: box-shadow
843+
Value: <<spread-shadow>>#
844+
Initial: none
845+
Applies to: all elements
846+
Inherited: no
847+
Percentages: N/A
848+
Computed value: either the keyword ''box-shadow-offset/none'' or
849+
a list, each item consisting of four absolute lengths
850+
plus a computed color and optionally also a ''box-shadow-position/inset'' keyword
851+
Animatable: by computed value,
852+
treating ''box-shadow-offset/none'' as a zero-item list
853+
and appending blank shadows (''transparent 0 0 0 0'')
854+
with a corresponding ''box-shadow-position/inset'' keyword as needed
855+
to match the longer list
856+
if the shorter list is otherwise compatible with the longer one
857+
</pre>
858+
859+
<p>The 'box-shadow' property attaches one or more drop-shadows to the box.
860+
The property accepts either the ''box-shadow-offset/none'' value, which indicates no shadows,
861+
or a comma-separated list of shadows, ordered front to back.
862+
863+
<p>Each shadow is given as a <<spread-shadow>>,
864+
outlining the 'box-shadow-offset', and optional values for the 'box-shadow-blur',
865+
'box-shadow-spread', 'box-shadow-color', and 'box-shadow-position'.
866+
Omitted lengths are 0; omitted colors default to the ''currentcolor'' value.
867+
<pre class=prod>
868+
<dfn><<spread-shadow>></dfn> = <<'box-shadow-color'>>? &amp;&amp; [ <<'box-shadow-offset'>> [ <<'box-shadow-blur'>> <<'box-shadow-spread'>>? ]? ] &amp;&amp; <<'box-shadow-position'>>?</pre>
869+
870+
<div class="example">
871+
<p>The example below demonstrates the effects of spread and blur on the shadow:
872+
<pre>
873+
<!-- -->width: <b>100px</b>; height: <b>100px</b>;
874+
<!-- -->border: <b>12px solid blue</b>; background-color: <b>orange</b>;
875+
<!-- -->border-top-left-radius: <b>60px 90px</b>;
876+
<!-- -->border-bottom-right-radius: <b>60px 90px</b>;
877+
<!-- -->box-shadow: <b>64px 64px 12px 40px rgba(0,0,0,0.4),
878+
<!-- --> 12px 12px 0px 8px rgba(0,0,0,0.4) inset</b>;
879+
</pre>
880+
<p class="figure">
881+
<img src="images/spread-blur.png"
882+
alt="The sample code above would create a 100px&times;100px orange box with a 12px blue border,
883+
whose top right / bottom left corners are sharp and tob left / bottom right corners are elliptically curved.
884+
Two shadows are created: an inner one, which due to its offset and spread creates a 20px-wide band of darker orange along the top and left sides of the box (curving to match the rounded top left border shape);
885+
and an outer one, creating a 204px&times;204px gray duplicate of the shape seemingly behind the box,
886+
offset 24px down and 24px to the right of the box's top and left edges.
887+
Applying the 12px blur radius to the outer shadow creates a gradual shift from the shadow color to transparent along its edges
888+
which is visibly apparent for 24px centered along the edge of the shadow.">
889+
</p>
890+
</div>
891+
892+
<h4 id="shadow-shape">
893+
Shadow Shape, Spread, and Knockout</h4>
894+
895+
<p>An <i>outer box-shadow</i> casts a shadow as if the border-box of the element were opaque.
896+
Assuming a spread distance of zero, its perimeter has the exact same size and shape as the border box.
897+
The shadow is drawn outside the border edge only:
898+
it is clipped inside the border-box of the element.
899+
900+
<p>An <i>inner box-shadow</i> casts a shadow as if everything outside the padding edge were opaque.
901+
Assuming a spread distance of zero, its perimeter has the exact same size and shape as the padding box.
902+
The shadow is drawn inside the padding edge only:
903+
it is clipped outside the padding box of the element.
904+
905+
<p>If a <i>spread distance</i> is defined, the shadow perimeter defined above
906+
is expanded outward (for <i>outer box-shadows</i>) or contracted inward (for <i>inner box-shadows</i>)
907+
by outsetting (insetting, for inner shadows) the shadow's straight edges by the <i>spread distance</i>
908+
(and flooring the resulting width/height at zero).
909+
910+
<div class="example">
911+
<p>Below are some examples of an orange box with a blue border being
912+
given a drop shadow.</p>
913+
914+
<table class="data" id="box-shadow-samples">
915+
<tr>
916+
<th scope="rowgroup">
917+
<pre><code><!--
918+
-->border:5px solid blue;
919+
<!-- -->background-color:orange;
920+
<!-- -->width: 144px;
921+
<!-- -->height: 144px;<!--
922+
--></code></pre>
923+
<th>
924+
<pre><code>border-radius: 20px;</code></pre>
925+
<th>
926+
<pre><code>border-radius: 0;</code></pre>
927+
<tr>
928+
<th>
929+
<pre><code><!--
930+
-->box-shadow:
931+
<!-- --> rgba(0,0,0,0.4)
932+
<!-- --> 10px 10px;<!--
933+
--></code></pre>
934+
<td>
935+
<img src="images/shadow-outer-round.png" width="175" height="175"
936+
alt="A round-cornered box with a light gray shadow the same shape
937+
as the border box offset 10px to the right and 10px down
938+
from directly underneath the box.">
939+
<td>
940+
<img src="images/shadow-outer-square.png" width="175" height="175"
941+
alt="A square-cornered box with a light gray shadow the same shape
942+
as the border box offset 10px to the right and 10px down
943+
from directly underneath the box.">
944+
<tr>
945+
<th>
946+
<pre><code><!--
947+
-->box-shadow:
948+
<!-- --> rgba(0,0,0,0.4)
949+
<!-- --> 10px 10px
950+
<!-- --> inset<!--
951+
--></code></pre>
952+
<td>
953+
<img src="images/shadow-inner-round.png" width="175" height="175"
954+
alt="A round-cornered box with a light gray shadow the inverse shape
955+
of the padding box filling 10px in from the top and left edges
956+
(just inside the border).">
957+
<td>
958+
<img src="images/shadow-inner-square.png" width="175" height="175"
959+
alt="A square-cornered box with a light gray shadow the inverse shape
960+
of the padding box filling 10px in from the top and left edges
961+
(just inside the border).">
962+
<tr>
963+
<th>
964+
<pre><code><!--
965+
-->box-shadow:
966+
<!-- --> rgba(0,0,0,0.4)
967+
<!-- --> 10px 10px 0
968+
<!-- --> 10px /* spread */<!--
969+
--></code></pre>
970+
<td>
971+
<img src="images/shadow-outer-spread-round.png" width="175" height="175"
972+
alt="A round-cornered box with a light gray shadow the same shape
973+
as the box but 20px taller and wider and offset so that the
974+
top and left edges of the shadow are directly underneath the
975+
top and left edges of the box.">
976+
<td>
977+
<img src="images/shadow-outer-spread-square.png" width="175" height="175"
978+
alt="A square-cornered box with a light gray shadow the same shape
979+
as the box but 20px taller and wider and offset so that the
980+
top and left edges of the shadow are directly underneath the
981+
top and left edges of the box.">
982+
<tr>
983+
<th>
984+
<pre><code><!--
985+
-->box-shadow:
986+
<!-- --> rgba(0,0,0,0.4)
987+
<!-- --> 10px 10px 0
988+
<!-- --> 10px /* spread */
989+
<!-- --> inset<!--
990+
--></code></pre>
991+
<td>
992+
<img src="images/shadow-inner-spread-round.png" width="175" height="175"
993+
alt="A round-cornered box with a light gray shadow the inverse shape
994+
of the box but 20px narrower and shorter filling 20px in from
995+
the top and left edges (just inside the border).">
996+
<td>
997+
<img src="images/shadow-inner-spread-square.png" width="175" height="175"
998+
alt="A round-cornered box with a light gray shadow the inverse shape
999+
of the box but 20px narrower and shorter filling 20px in from
1000+
the top and left edges (just inside the border).">
1001+
</tr>
1002+
</table>
1003+
</div>
1004+
1005+
<p>To preserve the box's shape when spread is applied,
1006+
the corner radii of the shadow are also increased (decreased, for inner shadows)
1007+
from the border-box (padding-box) radii by adding (subtracting)
1008+
the <i>spread distance</i> (and flooring at zero).
1009+
However, in order to create a sharper corner when the border radius is small
1010+
(and thus ensure continuity between round and sharp corners),
1011+
when the <i>border radius</i> is less than the <i>spread distance</i>
1012+
(or in the case of an inner shadow,
1013+
less than the absolute value of a negative <i>spread distance</i>),
1014+
the <i>spread distance</i>
1015+
is first multiplied by the proportion 1 + (<var>r</var>-1)<sup>3</sup>,
1016+
where <var>r</var> is the ratio of the border radius to the <i>spread distance</i>,
1017+
in calculating the corner radii of the spread shadow shape.
1018+
For example, if the border radius is 10px and the <i>spread distance</i> is 20px (<var>r</var> = .5),
1019+
the corner radius of the shadow shape will be 10px + 20px × (1 + (.5 - 1)<sup>3</sup>) = 27.5px
1020+
rather than 30px.
1021+
This adjustment is applied independently to the radii in each dimension.
1022+
1023+
<p>The 'border-image' does not affect the shape of the box-shadow.
1024+
1025+
<h4 id="shadow-blur">
1026+
Blurring Shadow Edges</h4>
1027+
1028+
<p>A non-zero <i>blur radius</i> indicates that the resulting shadow should
1029+
be blurred, such as by a Gaussian filter. The exact algorithm is not
1030+
defined; however the resulting shadow must approximate (with each pixel
1031+
being within 5% of its expected value) the image that would be generated
1032+
by applying to the shadow a Gaussian blur with a standard deviation equal
1033+
to half the blur radius
1034+
1035+
<p class="note">Note this means for a long, straight shadow edge, the
1036+
blur radius will create a visibly apparent color transition approximately
1037+
the twice length of the blur radius that is perpendicular to and centered
1038+
on the shadow's edge, and that ranges from almost the full shadow color at the
1039+
endpoint inside the shadow to almost fully transparent at the endpoint outside it.
1040+
1041+
<h4 id="shadow-layers">
1042+
Layering, Layout, and Other Details</h4>
1043+
1044+
<p>The shadow effects are applied front-to-back:
1045+
the first shadow is on top and the others are layered behind.
1046+
Shadows do not influence layout and may overlap (or be overlapped by)
1047+
other boxes and text or their shadows.
1048+
In terms of stacking contexts and the painting order,
1049+
the <i>outer box-shadows</i> of an element are drawn immediately below the background of that element,
1050+
and the <i>inner shadows</i> of an element are drawn immediately above the background of that element
1051+
(below the borders and border image, if any).
1052+
1053+
<p>If an element has multiple boxes, all of them get drop shadows,
1054+
but shadows are only drawn where borders would also be drawn;
1055+
see 'box-decoration-break'.
1056+
1057+
<p>Shadows do not trigger scrolling or increase the size of the scrollable area.
1058+
1059+
<p>Outer shadows have no effect on internal table elements in the collapsing border model.
1060+
If a shadow is defined for single border edge in the collapsing border model
1061+
that has multiple border thicknesses
1062+
(e.g. an outer shadow on a table where one row has thicker borders than the others,
1063+
or an inner shadow on a rowspanning table cell that adjoins cells with different border thicknesses),
1064+
the exact position and rendering of its shadows are undefined
1065+
6931066
<h2 id="changes">
6941067
Changes</h2>
6951068

0 commit comments

Comments
 (0)