css-forms-1/Overview.bs

<pre class="metadata">
Title: CSS Form Control Styling Module 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 ''&lt;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>
  &lt;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">&#x23B8;</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">&#x23B8;</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.&#x23B8;</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|&lt;input type=password&gt;}> 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">
    &lt;input type=password value=MySecret794>
    </code></pre>
    a user agent might render the <{input/type/password|&lt;input type=password&gt;}> 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;
}

select optgroup option {
  /* Undo font-weight:bolder rule from optgroups. */
  font-weight: normal;
}

select legend,
select option {
  /* spacing ownership moves to children */
  /* space inline from border edges */
  /* this creates a full bleed hover highlight */
  padding-inline: 0.5em;
}
```

### Drop-down box selects ### {#stylesheet-dropdown-select}

These styles should apply when the select is a [drop-down box](https://html.spec.whatwg.org/multipage/rendering.html#drop-down-box).

```css
select {
  field-sizing: content !important;
}

select > button:first-child {
  /* Prevents button from setting font, color, or background-color */
  all: unset;

  /* Prevents duplicate box decorations */
  display: contents;

  /* Prevents button activation behavior so select can handle events */
  interactivity: inert !important;
}

select::picker-icon {
  /* margin-inline-start pushes the icon to the right of the box */
  margin-inline-start: auto;
  display: block;
  content: counter(-ua-disclosure-open, disclosure-open);
}

::picker(select) {
  /* Same properties as popover and dialog */
  color: CanvasText;
  background-color: Canvas;
  border: 1px solid;

  /* box-sizing is set to match the button. */
  box-sizing: border-box;

  /* Remove [popover] padding which
   * prevents options from extending to edges */
  padding: 0;

  /* Anchor positioning and scrollbars */
  inset: auto;
  margin: 0;
  min-inline-size: anchor-size(self-inline);
  min-block-size: 1lh;
  /* Go to the edge of the viewport, and add scrollbars if needed. */
  max-block-size: stretch;
  overflow: auto;
  /* Below and span-right, by default. */
  position-area: block-end span-inline-end;
  position-try-order: most-block-size;
  position-try-fallbacks:
    /* First try above and span-right. */
    block-start span-inline-end,
    /* Then below but span-left. */
    block-end span-inline-start,
    /* Then above and span-left. */
    block-start span-inline-start;
}
```

### List box selects ### {#stylesheet-listbox-select}

These styles should apply when the select is a [list box](https://html.spec.whatwg.org/multipage/rendering.html#list-box).

```css
select {
	overflow: auto;
  display: inline-block;
  block-size: calc(max(24px, 1lh) * attr(size type(<integer>), 4));
}
```

<h2 class=no-num id=changes>Changes</h2>

<h3 class=no-num id=changes-20250325>Since the
  <a href="https://www.w3.org/TR/2025/WD-css-forms-1-20250325/">First
    Public Working Draft</a> of 25 March 2025</h3>

<ul>
  <li>Added !important to select buttons inertness.</li>
  <li>Removed "Appendix B: Explorations" with obsolete ideas.</li>
  <li>Added "slider-" prefix to slider pseudo-elements.</li>
  <li>Moved 'field-sizing' and 'input-security' properties from css-ui-4.</li>
  <li>Added the ''::reveal-icon'' pseudo-element.</li>
</ul>

<h2 class=no-num id=privacy>Privacy Considerations</h2>

No new privacy considerations have been reported on this specification.

<h2 class=no-num id=security>Security Considerations</h2>

No new security considerations have been reported on this specification.


<h2 class="no-num" id="acknowledgements">Acknowledgements</h2>

  Thanks to Aditya Keerthi, Anne van Kesteren, Elika Etemad, Jen Simmons, Joey Arhar, Jon Davis, Simon Fraser and Theresa O’Connor for their input on this proposal.

  Thanks to Ana Tudor for <a href="https://github.com/w3c/csswg-drafts/issues/4410#issuecomment-1087244943">her detailed analysis</a> of `input[type=range]` styling.