forked from w3c/csswg-drafts
-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathOverview.bs
More file actions
1117 lines (885 loc) · 37.6 KB
/
Copy pathOverview.bs
File metadata and controls
1117 lines (885 loc) · 37.6 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<pre class="metadata">
Title: CSS Form Control Styling Level 1
Shortname: css-forms
Level: 1
Repository: w3c/csswg-drafts
Prepare for TR: no
ED: https://drafts.csswg.org/css-forms-1/
TR: https://www.w3.org/TR/css-forms-1/
Editor: Tim Nguyen, w3cid 137443, Apple Inc. https://apple.com/, ntim@apple.com
Editor: Luke Warlow, w3cid 142912, Igalia, https://lukewarlow.dev
Abstract: This CSS Module defines various ways of styling form controls and their different parts.
Group: csswg
Status: ED
Work Status: Exploring
Markup Shorthands: css yes, markdown yes
</pre>
<pre class="link-defaults">
spec:css-forms-1; type:selector; for:/; text:::field-text
spec:css-forms-1; type:selector; for:/; text:::clear-icon
spec:css-forms-1; type:value; for:/; text:::placeholder
</pre>
# Introduction # {#intro}
<em>This section is non-normative.</em>
User agents have long provided non-standard ways of styling form controls.
However, all of these controls are implemented inconsistently across user agents,
creating unnecessary friction for authors.
This module aims to define a set of form control parts in enough detail that
they can be used interoperably.
It also defines some new ways of customizing form controls,
covering common use cases that were previously only possible by
implementing custom controls from scratch, which was a lot of work,
hard to get right, and often broke either accessibility or platform conventions.
# Opting Into [=Basic Appearance=]: the ''appearance: base'' value # {#appearance}
ISSUE: Move definition of ''appearance'' here.
<pre class="propdef partial">
Name: appearance
New values: base
</pre>
When applied on a form control, <dfn value for=appearance>base</dfn> puts that control in the <dfn>basic appearance</dfn> state.
A control that has [=basic appearance=] is consistently styleable using standard CSS and the pseudo-elements defined below, and applies overridable default styles that are consistent across UAs.
When a control is in that state, the user agent applies styles from the [[#basic-appearance-stylesheet]] to that control.
The user agent must also enable the pseudo-elements defined by [[#pseudo-elements]]. These pseudo-elements (excluding ''::picker()'') always
inherit 'appearance' from their [=originating element=]. The user agent may implement this using an ''appearance: inherit !important'' declaration.
NOTE: The inheritance prevents authors from mixing native and non-native parts for the same control.
## Design Principles for the [=Basic Appearance=] ## {#basic-appearance-principles}
The following design principles apply to the design of the [=basic appearance=] stylesheet for form controls,
in approximate order of descending importance:
1. The styles are identical in every user agent.
1. The controls are recognizable and usable on their own without additional styles.
1. The controls target accessiblity out of the box, ideally passing <a href="https://www.w3.org/TR/WCAG22/">WCAG 2.2 AA standards</a>.
NOTE: Authors may need to do extra adjustments to ensure their controls are accessible depending on any customizations as well as the context the form control is placed into.
The basic appearance does not prevent adjustments by the author that are inaccessible.
1. The styles are consistent across controls…
1. …in look & feel.
1. …in how they are defined in code.
1. …in sizing and interaction.
1. The styles are easily adapted to the website’s branding, without needing complex reset stylesheets:
1. They use minimal code and are easy to override.
1. They do not have a strong voice & tone of their own, and are visually as simple as possible.
1. They inherit page styles rather than define new styles whenever possible.
1. They are resilient to adjustments…
1. …when changed themselves (e.g. changing font, border, layout).
1. …when put in context (e.g. ready to be flex or grid children).
1. They are comprehensive:
1. Covering all states for each control.
1. Supporting all writing modes and color schemes.
For HTML form controls specifically, these principles are applied through the required user agent stylesheet defined in [[#basic-appearance-stylesheet]].
## Examples ## {#ex-appearance}
ISSUE: Refine these examples through implementation, experimentation, bikeshedding and improvements to the user agent stylesheet.
The main purpose of these examples is to show how the design principles for the [=basic appearance=] apply in practice.
To apply the [=basic appearance=] on individual controls, the following code is used:
<pre class="lang-css">
input, textarea, meter, progress, button, select {
appearance: base;
}
</pre>
NOTE: The form layout used by the following examples is not detailed.
### Default User Agent Colors ### {#colors}
Here are the [=basic appearance=] colors inheriting respectively the default light and dark mode colors from the root element:
<img src="images/base-screenshot.png" style="width: 50%; height: auto;" alt="Screenshot of the basic appearance with a light color scheme">
<img src="images/base-screenshot-dark.png" style="width: 50%; height: auto;" alt="Screenshot of the basic appearance with a dark color scheme">
### Color/Font Customization ### {#custom}
Here are some examples of customization being done on top of the [=basic appearance=]:
<div class="example">
<pre class="lang-css">
form {
font-family: "American Typewriter";
background-color: rgb(254, 252, 221);
color: rgb(131, 17, 0);
}
input, textarea, meter, progress, button, select {
appearance: base;
}
</pre>
<img src="images/base-example-1.png" style="width: 100%; height: auto;" alt="Screenshot of a customized basic appearance with brown text and a pale yellow background">
</div>
<div class="example">
<pre class="lang-css">
form {
font-family: "Courier New";
font-size: 14px;
background-color: rgb(0, 0, 0);
color: rgb(0, 249, 0);
}
input, textarea, meter, progress, button, select {
appearance: base;
}
</pre>
<img src="images/base-example-2.png" style="width: 100%; height: auto;" alt="Screenshot of a customized basic appearance with green text and a black background">
</div>
# Styling Pickers # {#pickers}
## The ''::picker()'' pseudo-element ## {#picker-pseudo}
The <dfn>::picker()</dfn> pseudo-element represents the part of the form control that pops out of the page.
<pre class=prod>
::picker() = ::picker( <<form-control-identifier>>+ )
<dfn for="::picker()"><<form-control-identifier>></dfn> = select
</pre>
The ''::picker()'' pseudo-element only matches when the [=originating
element=] supports [=basic appearance=] and has a popup picker. The
specified <<form-control-identifier>> must also match the <dfn>unique picker name</dfn> of the
[=originating element=]. For example, the [=unique picker name=] for
the <{select}> element is ''select''.
In order for the ''::picker()'' pseudo-element to be rendered, it and its
[=originating element=] must both have a [=computed value|computed=] 'appearance' of ''appearance/base''.
<div class="example">
The following styles apply the [=basic appearance=] to the select picker and the select and add some additional styling to the picker:
```css
select, select::picker(select) {
appearance: base;
}
select::picker(select) {
border: 5px solid red;
background-color: blue;
}
```
</div>
NOTE: The non-functional form of ''::picker()'' currently doesn't work to prevent unintended styling of pickers as new pickers become supported.
Once styling for all form control pickers is finalized, this non-functional form will work for all pickers.
# Pseudo-Elements # {#pseudo-elements}
Form controls are composed of many parts that authors may want to style separately,
hence the need for user agents to provide pseudo-elements for individual form controls.
The section below introduces a set of pseudo-elements that attempts to cover the most common use cases,
so they can be addressed in a consistent manner across user agents.
<table class="data">
<caption>Informative overview of form control pseudo-elements as applied to HTML</caption>
<thead>
<tr>
<th>Control</th>
<th>Pseudo-elements</th>
</tr>
</thead>
<tbody>
<tr>
<td>`<progress>`</td>
<td rowspan=4>
<pre>
├─ ''::slider-track''
│ └─ ''::slider-fill''
└─ ''::slider-thumb''
</pre>
</td>
</tr>
<tr>
<td>`<meter>`</td>
</tr>
<tr>
<td>`<input type=checkbox switch>`</td>
</tr>
<tr>
<td>`<input type=range>`</td>
</tr>
<tr>
<td>`<input type=checkbox>`</td>
<td rowspan="2">''::checkmark''</td>
</tr>
<tr>
<td>`<input type=radio>`</td>
</tr>
<tr>
<td>`<input type=file>`</td>
<td>''::file-selector-button''</td>
</tr>
<tr>
<td>`<input type=date>`</td>
<td rowspan=5>
* ''::field-component''
* ''::field-separator''
* ''::picker-icon''
See [[#date-time-pseudos]]
</td>
</tr>
<tr>
<td>`<input type=datetime-local>`</td>
</tr>
<tr>
<td>`<input type=time>`</td>
</tr>
<tr>
<td>`<input type=month>`</td>
</tr>
<tr>
<td>`<input type=week>`</td>
</tr>
<tr>
<td>`<input>` (with no type)</td>
<td rowspan=7>See [[#field-pseudos]]</td>
</tr>
<tr>
<td>`<input type=text>`</td>
</tr>
<tr>
<td>`<input type=search>`</td>
</tr>
<tr>
<td>`<input type=email>`</td>
</tr>
<tr>
<td>`<input type=password>`</td>
</tr>
<tr>
<td>`<input type=tel>`</td>
</tr>
<tr>
<td>`<input type=url>`</td>
</tr>
<tr>
<td>`<input type=number>`</td>
<td>See [[#number-pseudos]]</td>
</tr>
<tr>
<td>`<input type=color>`</td>
<td>''::color-swatch''</td>
</tr>
<tr>
<td>`<textarea>`</td>
<td>See [[#textarea-pseudos]]</td>
</tr>
<tr>
<td>`<select>`</td>
<td>''::picker-icon''</td>
</tr>
<tr>
<td>`<option>`</td>
<td>''::checkmark''</td>
</tr>
<tr>
<td>Buttons</td>
<td></td>
</tr>
</tbody>
</table>
ISSUE: Add illustrations.
## Picker Opener Icon: the ''::picker-icon'' pseudo-element ## {#picker-icon}
The <dfn>::picker-icon</dfn> pseudo-element represents the part of the control that represents the icon denoting the presence of the picker.
It is only generated when the [=originating element=] has [=basic appearance=] and if it opens a picker.
It is a [=fully styleable pseudo-element=] and inherits from its [=originating element=].
''::picker-icon'' generates a box as if it was an child of its
[=originating element=], after any boxes generated by the ''::after''
pseudo-element, with content as specified by 'content'.
## File Selector Button: the ''::file-selector-button'' pseudo-element ## {#file-selector-button-pseudo}
The <dfn>::file-selector-button</dfn> pseudo-element represents the button used to open a file picker, if the UA renders such a button.
It typically targets the <{button}> inside an <{input}> element with `type=file`.
<div class="example" id="file-selector-button-example">
For example, the following example should show a green border around the
file selector button:
<pre class="lang-css">::file-selector-button { border: 3px solid green }</pre>
</div>
## Styling Checkmarks: the ''::checkmark'' pseudo-element ## {#checkmark}
The <dfn>::checkmark</dfn> pseudo-element represents an indicator of whether the item is checked, and is present on checkboxes, radios, and option elements.
It is only generated when the [=originating
element=] supports the '':checked'' pseudo-class, and either has [=basic
appearance=] or an ancestor with [=basic appearance=].
It is a [=fully styleable pseudo-element=] and inherits from its [=originating element=].
For checkboxes and radio elements, it generates a box as if it was an child of its [=originating
element=], between the boxes generated by the ''::before'' and ''::after''
pseudo-element, with content as specified by 'content'.
For option elements, it generates a box as if it was an child of its <a>originating
element</a>, preceding any boxes generated by the ''::before''
pseudo-element, with content as specified by 'content'.
<div class="example">
The following example changes the background image of a checkmark:
<pre class="lang-css">::checkmark { background-image: url(...) }</pre>
It may also be used in combination with `:indeterminate` to style the indeterminate checkmark:
<pre class="lang-css">:indeterminate::checkmark { background-image: url(...) }</pre>
</div>
## Styling Parts of [=Slider-Like Controls=]: the ''::slider-thumb'', ''::slider-track'' and ''::slider-fill'' pseudo-elements ## {#slider-pseudos}
<dfn>Slider-like controls</dfn> are form controls that represent progress.
That progress may be adjustable by the user.
The following pseudo-elements are provided to style their different parts:
<dl export>
<dt><dfn>::slider-thumb</dfn>
<dd>
The ''::slider-thumb'' pseudo-element represents
the portion that allows the user to adjust the progress of the control.
NOTE: It is typically natively rendered as a circle in most user agents.
<dt><dfn>::slider-track</dfn>
<dd>
The ''::slider-track'' pseudo-element represents the portion containing
both the progressed and unprogressed portions of the control.
<dt><dfn>::slider-fill</dfn>
<dd>
The ''::slider-fill'' pseudo-element represents
the portion containing the progressed portion of the control.
When the progress of control is indeterminate (like with ''<progress>''),
the user agent must give this portion an inline-size of zero.
</dl>
These pseudo-elements are [=fully styleable pseudo-elements=] and their structure is the following:
```
<input type="range">
├─ ::slider-track
│ └─ ::slider-fill
└─ ::slider-thumb
```
The list of [=slider-like controls=] depends on the host language. For HTML, this corresponds to:
- <{progress}>
- <{meter}>
- <{input}> elements with `type="range"`
- <{input}> elements with `type="checkbox" switch`
## Styling Parts for Text Fields: the ''::placeholder'', ''::field-text'', ''::reveal-icon'', and ''::clear-icon'' pseudo-elements ## {#field-pseudos}
<dl export>
<dt><dfn>::placeholder</dfn>
<dd>
The ''::placeholder'' pseudo-element represents
the portion of the <{input}> that contains the placeholder text.
<dt><dfn>::field-text</dfn>
<dd>
The ''::field-text'' pseudo-element represents
the portion of the <{input}> that contains the editable text.
<dt><dfn>::reveal-icon</dfn>
<dd>
The ''::reveal-icon'' pseudo-element represents
the portion of the <{input}> that allows the user to
temporarily disable obscuring of [=sensitive text input=]
when clicked if provided by the user agent.
User agents providing ''::reveal-icon'' may choose to
remove it in some circumstances to help protect [=sensitive text input=]
from being revealed unintentionally.
<div class=note>
Example mitigations to avoid unintentionally revealing [=sensitive text input=]:
<ul>
<li>If focus moves away from the field, remove the ''::reveal-icon''.</li>
<li>If script modifies field content, remove the ''::reveal-icon''.</li>
<li>If the ''::reveal-icon'' is removed due to either of the above,
the user must delete the contents of the field to make the
''::reveal-icon'' appear again. This behavior prevents someone
from making a minor change to field content to expose the
''::reveal-icon'' on an unattended device.</li>
<li>If the field is filled by a user agent autofill feature, remove
the ''::reveal-icon''.</li>
</ul>
</div>
<dt><dfn>::clear-icon</dfn>
<dd>
The ''::clear-icon'' pseudo-element represents
the portion of the <{input}> that allows the user to
clear the <{input}> when clicked if provided by the
user agent.
With ''appearance: textfield'', the user agent must not generate this part.
</dl>
''::field-text'', ''::reveal-icon'', and ''::clear-icon'' must be siblings.
ISSUE: Collect parts used by autofill.
ISSUE(11844): Define how `::placeholder` interacts with `::field-text`.
## Styling Parts for textareas: the ''::placeholder'' and ''::field-text'' pseudo-elements ## {#textarea-pseudos}
<dl export>
<dt><span>''::placeholder''</span>
<dd>
The ''::placeholder'' pseudo-element represents
the portion of the <{textarea}> that contains the placeholder text.
<dt><span>''::field-text''</span>
<dd>
The ''::field-text'' pseudo-element represents
the portion of the <{textarea}> that contains the editable text.
</dl>
ISSUE(11850): Define something for the resizer.
ISSUE(11844): Define how `::placeholder` interacts with `::field-text`.
## Styling Parts for Number Fields: the ''::step-control'', ''::step-up'' and ''::step-down'' pseudo-elements ## {#number-pseudos}
These pseudo-elements are provided for number inputs. They are [=fully styleable pseudo-elements=].
<dl export>
<dt><dfn>::step-control</dfn>
<dd>
The ''::step-control'' pseudo-element represents
the portion of a number input that contains the up and down buttons.
<dt><dfn>::step-up</dfn>
<dd>
The ''::step-up'' pseudo-element represents
the button that increments the value inside a number input when activated.
<dt><dfn>::step-down</dfn>
<dd>
The ''::step-down'' pseudo-element represents
the button that decrements the value inside a number input when activated.
</dl>
Their structure is defined as follows:
```
<input type="number">
├─ ::field-text
└─ ::step-control
├─ ::step-up
└─ ::step-down
```
<div class=example id=number-styling>
The following control:
<xmp highlight=html><input type="number"></xmp>
can be re-styled like this:
`[ + 2 - ]`
ISSUE: Insert real image.
using the following styles:
```css
input[type=number] {
appearance: base;
&::step-control {
display: contents;
}
&::step-up {
order: 1;
content: "+";
}
&::field-text {
order: 2;
}
&::step-down {
order: 3;
content: "-";
}
}
```
</div>
With ''appearance: textfield'', the user agent must not generate this part.
## Styling Parts for Date/Time Input Fields: the ''::field-component'' and ''::field-separator'' pseudo-elements ## {#date-time-pseudos}
<dl export>
<dt><dfn>::field-component</dfn>
<dd>
The ''::field-component'' pseudo-element represents
the portions of the control that contain the date/time component values.
<dt><dfn>::field-separator</dfn>
<dd>
The ''::field-separator'' pseudo-element represents
the portions of the control that separate the date/time component values if the user agent provides those portions.
</dl>
Those pseudo-elements are siblings. The exact structure of the control is determined by internationalization and by the host language,
but must be consistent across user-agents.
<div class=example id=date-input-pseudo-element-structure>
The following control:
<xmp highlight=html><input type="date"></xmp>
may render like this in US locales:
[ 08 / 22 / 2024 [v]]
ISSUE: Insert real image.
The resulting tree is:
```
<input type="date">
├─ ::field-component (08)
├─ ::field-separator (/)
├─ ::field-component (22)
├─ ::field-separator (/)
├─ ::field-component (2024)
└─ ::picker-icon
```
</div>
## Color Swatch: the ''::color-swatch'' pseudo-element ## {#color-swatch-pseudo}
The <dfn>::color-swatch</dfn> pseudo-element represents the portion of the control that displays the chosen color value.
<div class="example" id="color-swatch-example">
For example, the following example should make the input and its color swatch rounded:
<pre class="lang-css">input[type=color], ::color-swatch { border-radius: 100%; }</pre>
</div>
## Compatibility With Vendor Pseudo-Element Extensions ## {#vendor-pseudo-element-compatibility}
When possible, the user agent should use aliasing to implement any non-standard pseudo-elements.
When not possible, the user agent must reserve the standard pseudo-elements for ''appearance: base''
and use any non-standard ones for ''appearance: none''.
# Pseudo-Classes # {#pseudo-classes}
## Targeting Different Meter States: the '':low-value'' / '':high-value'' / '':optimal-value'' pseudo-classes ## {#meter-values}
ISSUE(11336): Make sure this is able to replicate UA logic.
ISSUE: Link these to the HTML definitions.
The <dfn>:low-value</dfn> pseudo-class matches on a <{meter}> element when its value is under the value specified by the `low` HTML attribute.
The <dfn>:high-value</dfn> pseudo-class matches on a <{meter}> element when its value is over the value specified by the `high` HTML attribute.
The <dfn>:optimal-value</dfn> pseudo-class matches on a <{meter}> element when its value is in the range determined by the `optimum` / `low` / `high` HTML attributes.
## Targeting Selects that are Listboxes ## {#selects-listboxes}
ISSUE(7422): Define something.
# The ''control-value()'' function # {#control-value}
ISSUE: This is not ready for implementation, file an issue regarding this.
ISSUE(11860): Consider privacy implications, regarding data exfiltration.
ISSUE(11842): Consider adding more types.
The <dfn>control-value()</dfn> function computes to the current value of the form control it is on. If it is used on an element that is not a form control,
it returns an empty string.
<pre class=prod>
<control-value()> = control-value( <<type>>? )
<dfn><<type>></dfn> = '<' [ number | string ] '>'
</pre>
If used on a pseudo-element, it is evaluated against its originating element.
<div class="example" id="range-input-control-value-example">
For example, to show on the value of a range input next to it:
<pre class="lang-css">
input[type=range]::after {
content: control-value();
}
</pre>
</div>
# Styling Widgets # {#styling-widgets}
## Widget Accent Colors: the 'accent-color' property ## {#accent-color}
The 'accent-color' property is defined in [[!CSS-UI-4]].
## Switching form control sizing: the 'field-sizing' property ## {#field-sizing}
<pre class=propdef>
Name: field-sizing
Value: fixed | content
Initial: ''field-sizing/fixed''
Applies to: [=elements with default preferred size=]
Inherited: no
Percentages: N/A
Computed Value: as specified
Canonical order: per grammar
Animation type: discrete
</pre>
For the purpose of this specification,
an <dfn export>element with default preferred size</dfn> is an element
whose [=intrinsic size=] is fixed regardless of the size of its content.
The host language defines which elements are applicable to it.
For example, in HTML <{textarea}> is an [=element with default preferred size=].
<dl dfn-type=value dfn-for=field-sizing>
<dt><dfn>fixed</dfn>
<dd>
For [=element with default preferred size=],
the UA must set the [=intrinsic size=]
to the default preferred size defined by the host language for that element.
Otherwise, the UA must behave the same as ''field-sizing/content''.
<dt><dfn>content</dfn>
<dd>
The UA must determine the element's [=intrinsic size=] based on its content,
and must ignore any default preferred size defined by the host language for that element.
If the element is an [=element with default preferred size=] and
is listed in [[CSS-SIZING-3#min-content-zero|compressible replaced elements]],
the UA must stop treating the element as a replaced element for [=min-content contribution=].
</dl>
<div class="example">
For instance, <{textarea}> has a fixed size regardless of its content by default:
<span class="fake-textarea auto">⎸</span>
<span class="fake-textarea auto">The quick brown fox jumps over the lazy dog.</span>
If ''field-sizing: content'' is applied, the size of the former should fit to a text caret.
<span class="fake-textarea">⎸</span>
If ''field-sizing: content'' is applied and its width property has a fixed value like ''width: 10em'',
the element height depends on the number of the content lines:
<span class="fake-textarea normal">The quick brown fox jumps over the lazy dog.⎸</span>
</div>
## Changing the Orientation of a [=Slider-Like Control=]: ''slider-orientation'' ## {#slider-orientation}
ISSUE: Rework this property.
<pre class=propdef>
Name: slider-orientation
Value: auto | left-to-right | right-to-left | top-to-bottom | bottom-to-top
Initial: auto
Inherited: no
Percentages: n/a
Computed Value: as specified
Animation type: discrete
</pre>
<dl dfn-type=value dfn-for=slider-orientation>
<dt><dfn>auto</dfn></dt>
<dd>
The [=slider-like control=] orientation is defined by the writing mode and direction.
<dt><dfn>left-to-right</dfn></dt>
<dd>
The [=slider-like control=] is rendered horizontally and ''::slider-fill'' is left-aligned within the control.
<dt><dfn>right-to-left</dfn></dt>
<dd>
The [=slider-like control=] is rendered horizontally and ''::slider-fill'' is right-aligned within the control.
<dt><dfn>top-to-bottom</dfn></dt>
<dd>
The [=slider-like control=] is rendered vertically and ''::slider-fill'' is top-aligned within the control.
<dt><dfn>bottom-to-top</dfn></dt>
<dd>
The [=slider-like control=] is rendered vertically and ''::slider-fill'' is bottom-aligned within the control.
</dl>
## Obscuring sensitive input: the 'input-security' property ## {#input-security}
Issue: The CSSWG has agreed that
while we believe that providing this piece of functionality to users is important,
doing it via CSS+JS is the wrong approach,
and that instead it should be built into user agents:
this needs to work consistently from site to site for it to be discoverable and understandable by users,
this needs to work even when JS is turned off,
and this needs to have consistently solid accessibility…
We therefore intend to remove this from the specification,
and instead, we would like to see this behavior specified in the HTML specification
as part of the interaction model of password fields.
Holding off deleting until the situation with HTML is clarified.
See
<a href="https://github.com/w3c/csswg-drafts/issues/6788">https://github.com/w3c/csswg-drafts/issues/6788</a>
and
<a href="https://github.com/whatwg/html/issues/7293">https://github.com/whatwg/html/issues/7293</a>.
<pre class=propdef>
Name: input-security
Value: auto | none
Initial: ''input-security/auto''
Applies to: [=sensitive text inputs=]
Inherited: no
Percentages: N/A
Computed Value: as specified
Canonical order: per grammar
Animation type: by computed value type
</pre>
For the purpose of this specification,
a <dfn export>sensitive text input</dfn> is
a text input whose purpose is to accept sensitive input,
as defined by the host language.
For example, in HTML <{input/type/password|<input type=password>}> is a [=sensitive text input=].
By default, user agents obscure the contents of [=sensitive text inputs=]
in order to prevent onlookers from seeing it.
Users may wish to temporarily disable this obscuring
in order to confirm that they've typed their sensitive information correctly.
The ''input-security'' property may be used by authors
to enable or disable this obscuring.
<dl dfn-type=value dfn-for=input-security>
<dt><dfn>none</dfn>
<dd>
The UA must not obscure the text in the control,
so that it can be read by the user.
<dt><dfn>auto</dfn>
<dd>
The UA should obscure the text in the control,
so that it cannot be read by the user.
</dl>
While the exact mechanism by which user agents obscure the text in the control is undefined, user agents typically obscure [=sensitive text inputs=] by replacing each character with some suitable replacement such as U+002A ASTERISK (*) or U+25CF BLACK CIRCLE (●).
<div class="example">
For instance, given this style sheet
<pre><code class="lang-css">
input[type=password] {
input-security: auto;
}</code></pre>
and this HTML
<pre><code class="lang-html">
<input type=password value=MySecret794>
</code></pre>
a user agent might render the <{input/type/password|<input type=password>}> like so:
<span class=fake-input-type-password>●●●●●●●●●●●</span>
</div>
<h2 class="no-num non-normative" id="basic-appearance-stylesheet">Appendix A: Basic Appearance User Agent Stylesheet</h2>
ISSUE: Move to HTML.
ISSUE: This section needs refining with implementation.
ISSUE(11837): Color input styles need refining.
## Basics ## {#stylesheet-basics}
```css
input,
textarea,
button,
::file-selector-button,
select,
meter,
progress {
color: inherit;
font: inherit;
box-sizing: border-box;
background-color: transparent;
}
```
## Layout ## {#stylesheet-layout}
```css
input:not([type=file], [type=range], [type=checkbox][switch]),
textarea,
button,
::file-selector-button,
::slider-track,
select {
border: 1px solid currentColor;
background-color: transparent;
}
```
## Sliders ## {#stylesheet-sliders}
ISSUE: Refine meter, progress, switch and range input styling.
```css
::slider-track {
height: 1em;
}
::slider-fill {
height: 100%;
background-color: currentColor;
}
:indeterminate::slider-fill {
inline-size: 0;
}
::slider-thumb {
border-radius: 0;
border: none;
background-color: currentColor;
appearance: none;
width: 1em;
height: 100%;
}
```
## Checkboxes & radios ## {#stylesheet-checkbox-radio}
```css
input:is([type=checkbox]:not([switch]), [type=radio]) {
width: 1em;
height: 1em;
display: inline-flex;
align-items: center;
justify-content: center;
content: '';
}
input[type=radio] {
border-radius: 100%;
}
input[type=checkbox]:not([switch]):checked::checkmark {
content: '\2713' / '';
}
input[type=radio]:checked::checkmark {
background-color: currentColor;
display: inline-block;
border-radius: inherit;
height: 100%;
width: 100%;
}
```
## Buttons (and button-like controls) ## {#stylesheet-button}
Selects are only button-like when they're a [drop-down box](https://html.spec.whatwg.org/multipage/rendering.html#drop-down-box).
```css
button,
::file-selector-button,
select,
input:is([type="color"], [type="button"], [type="reset"], [type="submit"]) {
border: 1px solid currentColor;
background-color: transparent;
color: inherit;
/* Padding prevents the text from sticking to the borders.
* optically centered to account for half leading */
padding-block: 0.25em;
padding-inline: 0.5em;
/* <select>s and <button>s should have border-radius to be
* distinct from <input>s: https://github.com/w3c/csswg-drafts/issues/10857#issuecomment-2520875011*/
border-radius: 0.5em;
/* These min-size rules ensure accessibility by following WCAG rules:
* https://www.w3.org/WAI/WCAG22/Understanding/target-size-minimum.html
* The 1lh is there to make sure that options without text don't change
* the block size of the button. */
min-block-size: calc-size(auto, max(size, 24px, 1lh));
min-inline-size: calc-size(auto, max(size, 24px));
/* box-sizing comes from existing UA styles which happen to
* already be interoperable. */
box-sizing: border-box;
/* Push picker icon to the right of the box and have some space
* in between it and the text. */
display: inline-flex;
gap: 0.5em;
user-select: none;
text-transform: initial;
text-align: initial;
text-indent: initial;
}
:is(button, select, input:is([type="color"], [type="button"], [type="reset"], [type="submit"])):enabled:hover,
:enabled::file-selector-button:hover {
background-color: color-mix(in lab, currentColor 10%, transparent);
}
:is(button, select, input:is([type="color"], [type="button"], [type="reset"], [type="submit"])):enabled:active,
:enabled::file-selector-button:active {
background-color: color-mix(in lab, currentColor 20%, transparent);
}
:is(button, select, input:is([type="color"], [type="button"], [type="reset"], [type="submit"])):disabled,
:disabled::file-selector-button {
color: color-mix(in srgb, currentColor 50%, transparent);
}
```
## Selects ## {#stylesheet-select}
```css
select option {
/* These min-size rules ensure accessibility by following WCAG rules:
* https://www.w3.org/WAI/WCAG22/Understanding/target-size-minimum.html
* Unset if the author provides a child button element.
* The 1lh is there to make sure that options without text don't change
* the block size of the option. */
min-inline-size: 24px;
min-block-size: max(24px, 1lh);
/* Centers text within the block (vertically). From OpenUI discussion:
* https://github.com/openui/open-ui/issues/1026#issuecomment-2103187647. */
align-content: center;
/* centering + gap between checkmark and option content */
/* also easily reversed, when checkmark should be inline-end */
display: flex;
align-items: center;
gap: 0.5em;
/* Makes options with long text widen picker instead
* of making options tall. */
white-space: nowrap;
}
select option:enabled:hover {
background-color: color-mix(in lab, currentColor 10%, transparent);
}
select option:enabled:active {
background-color: color-mix(in lab, currentColor 20%, transparent);
}
select option:disabled {
color: color-mix(in lab, currentColor 50%, transparent);
}
select option::checkmark {
content: '\2713' / '';
}
select option:not(:checked)::checkmark {
visibility: hidden;
}
select optgroup {
/* font-weight makes optgroups visually distinct from options. */
font-weight: bolder;