css-has-pseudo
    TypeScript icon, indicating that this package has built-in type declarations

    4.0.1 • Public • Published

    PostCSS Has Pseudo PostCSS Logo

    npm version CSS Standard Status Build Status Discord

    PostCSS Has Pseudo lets you style elements relative to other elements in CSS, following the Selectors Level 4 specification.

    .title:has(+ p) {
    	margin-bottom: 1.5rem;
    }
    
    /* becomes */
    
    .js-has-pseudo [csstools-has-1a-38-2x-38-30-2t-1m-2w-2p-37-14-17-w-34-15]:not(does-not-exist) {
    	margin-bottom: 1.5rem;
    }
    .title:has(+ p) {
    	margin-bottom: 1.5rem;
    }

    Usage

    Add PostCSS Has Pseudo to your project:

    npm install postcss css-has-pseudo --save-dev

    Use it as a PostCSS plugin:

    const postcss = require('postcss');
    const postcssHasPseudo = require('css-has-pseudo');
    
    postcss([
    	postcssHasPseudo(/* pluginOptions */)
    ]).process(YOUR_CSS /*, processOptions */);

    PostCSS Has Pseudo runs in all Node environments, with special instructions for:

    Node PostCSS CLI Webpack Create React App Gulp Grunt

    Options

    preserve

    The preserve option determines whether the original notation is preserved. By default the original rules are preserved.

    postcssHasPseudo({ preserve: false })
    .title:has(+ p) {
    	margin-bottom: 1.5rem;
    }
    
    /* becomes */
    
    .js-has-pseudo [csstools-has-1a-38-2x-38-30-2t-1m-2w-2p-37-14-17-w-34-15]:not(does-not-exist) {
    	margin-bottom: 1.5rem;
    }

    specificityMatchingName

    The specificityMatchingName option allows you to change to selector that is used to adjust specificity. The default value is does-not-exist. If this is an actual class, id or tag name in your code, you will need to set a different option here.

    See how :not is used to modify specificity.

    postcssHasPseudo({ specificityMatchingName: 'something-random' })

    specificity 1, 2, 0

    Before :

    .x:has(> #a:hover) {
    	order: 11;
    }

    After :

    specificity 1, 2, 0

    [csstools-has-1a-3c-1m-2w-2p-37-14-1q-w-z-2p-1m-2w-33-3a-2t-36-15]:not(#does-not-exist):not(.does-not-exist) {
    	order: 11;
    }

    ⚠️ Known shortcomings

    Specificity

    :has transforms will result in at least one attribute selector with specificity 0, 1, 0.
    If your selector only has tags we won't be able to match the original specificity.

    Before :

    specificity 0, 0, 2

    figure:has(> img)

    After :

    specificity 0, 1, 2

    [csstools-has-2u-2x-2v-39-36-2t-1m-2w-2p-37-14-1q-w-2x-31-2v-15]:not(does-not-exist):not(does-not-exist)

    Plugin order

    As selectors are encoded, this plugin (or postcss-preset-env) must be run after any other plugin that transforms selectors.

    If other plugins are used, you need to place these in your config before postcss-preset-env or css-has-pseudo.

    Please let us know if you have issues with plugins that transform selectors. Then we can investigate and maybe fix these.

    Browser

    // initialize prefersColorScheme (applies the current OS color scheme, if available)
    import cssHasPseudo from 'css-has-pseudo/browser';
    cssHasPseudo(document);

    or

    <!-- When using a CDN url you will have to manually update the version number -->
    <script src="https://unpkg.com/css-has-pseudo@4.0.1/dist/browser-global.js"></script>
    <script>cssHasPseudo(document)</script>

    ⚠️ Please use a versioned url, like this : https://unpkg.com/css-has-pseudo@4.0.1/dist/browser-global.js Without the version, you might unexpectedly get a new major version of the library with breaking changes.

    PostCSS Has Pseudo works in all major browsers, including Internet Explorer 11. With a Mutation Observer polyfill, the script will work down to Internet Explorer 9.

    Browser Usage

    hover

    The hover option determines if :hover pseudo-class should be tracked. This is disabled by default because it is an expensive operation.

    cssHasPseudo(document, { hover: true });

    observedAttributes

    The observedAttributes option determines which html attributes are observed. If you do any client side modification of non-standard attributes and use these in combination with :has() you should add these here.

    cssHasPseudo(document, { observedAttributes: ['something-not-standard'] });

    forcePolyfill

    The forcePolyfill option determines if the polyfill is used even when the browser has native support. This is needed when you set preserve: false in the PostCSS plugin config.

    cssHasPseudo(document, { forcePolyfill: true });

    debug

    The debug option determines if errors are emitted to the console in browser. By default the polyfill will not emit errors or warnings.

    cssHasPseudo(document, { debug: true });

    Browser Dependencies

    Web API's:

    ECMA Script:

    • Array.prototype.filter
    • Array.prototype.forEach
    • Array.prototype.indexOf
    • Array.prototype.join
    • Array.prototype.map
    • Array.prototype.splice
    • RegExp.prototype.exec
    • String.prototype.match
    • String.prototype.replace
    • String.prototype.split

    CORS

    ⚠️ Applies to you if you load CSS from a different domain than the page.

    In this case the CSS is treated as untrusted and will not be made available to the JavaScript polyfill. The polyfill will not work without applying the correct configuration for CORS.

    Example :

    page css CORS applies
    https://example.com/ https://example.com/style.css no
    https://example.com/ https://other.com/style.css yes

    You might see one of these error messages :

    Chrome :

    DOMException: Failed to read the 'cssRules' property from 'CSSStyleSheet': Cannot access rules

    Safari :

    SecurityError: Not allowed to access cross-origin stylesheet

    Firefox :

    DOMException: CSSStyleSheet.cssRules getter: Not allowed to access cross-origin stylesheet

    To resolve CORS errors you need to take two steps :

    • add an HTTP header Access-Control-Allow-Origin: <your-value> when serving your CSS file.
    • add crossorigin="anonymous" to the <link rel="stylesheet"> tag for your CSS file.

    In a node server setting the HTTP header might look like this :

    // http://localhost:8080 is the domain of your page!
    res.setHeader('Access-Control-Allow-Origin', 'https://example.com');

    You can also configure a wildcard but please be aware that this might be a security risk. It is better to only set the header for the domain you want to allow and only on the responses you want to allow.

    HTML might look like this :

    <link rel="stylesheet" href="https://example.com/styles.css" crossorigin="anonymous">

    How it works

    The PostCSS Has Pseudo clones rules containing :has(), replacing them with an alternative [csstools-has-] selector.

    .title:has(+ p) {
    	margin-bottom: 1.5rem;
    }
    
    /* becomes */
    
    .js-has-pseudo [csstools-has-1a-38-2x-38-30-2t-1m-2w-2p-37-14-17-w-34-15]:not(does-not-exist) {
    	margin-bottom: 1.5rem;
    }
    .title:has(+ p) {
    	margin-bottom: 1.5rem;
    }

    Next, the browser script adds a [:has] attribute to elements otherwise matching :has natively.

    <div class="title" [csstools-has-1a-38-2x-38-30-2t-1m-2w-2p-37-14-17-w-34-15]>
    	<h1>A title block</h1>
    	<p>With an extra paragraph</p>
    </div>

    Install

    npm i css-has-pseudo

    DownloadsWeekly Downloads

    5,557,996

    Version

    4.0.1

    License

    CC0-1.0

    Unpacked Size

    192 kB

    Total Files

    14

    Last publish

    Collaborators

    • alaguna
    • jonathantneal