Plumeria logo/ ✾ Plumeria
API reference

Pseudo Utility

The ps(Pseudo) utility in the @plumeria/core package provides a powerful way to apply CSS pseudo-classes and pseudo-elements programmatically. You can use these utilities as selectors within an array or combine multiple pseudo states using the cx function. This reference covers all available pseudo-classes, pseudo-elements, and functional pseudo selectors, with detailed descriptions and usage examples.

Overview

The ps(Pseudo) utility allows developers to apply CSS pseudo-classes and pseudo-elements directly within JavaScript or TypeScript code using @plumeria/core. This is particularly useful for dynamic styling in modern web applications, such as single-page apps or component-based frameworks. By leveraging these utilities, you can create responsive and interactive styles with minimal CSS boilerplate.

Usage

import { ps } from '@plumeria/core';

Pseudo-Classes

Standard Pseudo-Classes

Pseudo-classes target elements based on their state, position, or user interaction. Below is a comprehensive list of all supported pseudo-classes in the pseudo utility.

Pseudo-ClassDescriptionExample Use Case
ps.activeStyles an element when it is being activated (e.g., clicked).Highlight a button during a click event.
ps.anyLinkTargets any link, whether visited or unvisited.Style all anchor tags uniformly.
ps.autoFillTargets form elements auto-filled by the browser.Customize the appearance of auto-filled input fields.
ps.bufferingStyles media elements (e.g., <video>) while buffering.Display a loading state for a video player.
ps.checkedTargets checked form elements (e.g., checkboxes, radio buttons).Style checked radio buttons or checkboxes.
ps.defaultTargets the default element among a group (e.g., default button in a form).Highlight the default submit button.
ps.definedTargets elements that are defined (e.g., custom elements with a definition).Style custom web components after definition.
ps.disabledTargets disabled form elements or controls.Gray out disabled buttons or inputs.
ps.emptyTargets elements with no children or text content.Hide empty <div> elements.
ps.enabledTargets enabled form elements or controls.Style enabled inputs differently from disabled ones.
ps.firstTargets the first element in a group (e.g., in a :where() context).Style the first item in a dynamic list.
ps.firstChildTargets the first child of a parent element.Style the first <p> in a <div>.
ps.firstOfTypeTargets the first sibling of its type.Style the first <h1> among siblings.
ps.focusTargets an element that has focus (e.g., via keyboard or click).Add an outline to focused input fields.
ps.focusVisibleTargets an element with visible focus (e.g., keyboard navigation).Show focus ring only for keyboard users.
ps.focusWithinTargets an element containing a focused descendant.Style a form when any input inside is focused.
ps.fullscreenTargets an element in fullscreen mode.Style a video player in fullscreen.
ps.futureTargets elements in a timeline context (e.g., Temporal API).Style future dates in a calendar.
ps.hasSlottedTargets shadow DOM hosts with slotted content.Style elements with slotted children in shadow DOM.
ps.hostTargets the shadow DOM host element.Style the root of a shadow DOM.
ps.hoverStyles an element when the mouse hovers over it.Change background color on hover.
ps.inRangeTargets form elements with values within a valid range.Highlight valid range inputs.
ps.indeterminateTargets checkboxes or radio buttons in an indeterminate state.Style indeterminate checkboxes.
ps.invalidTargets form elements with invalid input.Highlight invalid input fields.
ps.lastChildTargets the last child of a parent element.Style the last <li> in a list.
ps.lastOfTypeTargets the last sibling of its type.Style the last <p> among siblings.
ps.leftTargets elements in a paged context (e.g., print layouts).Style left-hand pages in a print stylesheet.
ps.linkTargets unvisited links.Style unvisited <a> tags.
ps.modalTargets elements in a modal state (e.g., dialogs).Style modal dialogs.
ps.mutedTargets media elements that are muted.Style muted video players.
ps.onlyChildTargets an element that is the only child of its parent.Style a lone <span> in a <div>.
ps.onlyOfTypeTargets an element that is the only one of its type among siblings.Style a single <h2> among siblings.
ps.openTargets open <details> or <dialog> elements.Style open accordion sections.
ps.optionalTargets form elements that are not required.Style optional input fields.
ps.outOfRangeTargets form elements with values outside a valid range.Highlight out-of-range inputs.
ps.pastTargets elements in a timeline context (e.g., Temporal API).Style past dates in a calendar.
ps.pausedTargets paused media elements.Style paused video players.
ps.pictureInPictureTargets elements in picture-in-picture mode.Style videos in PIP mode.
ps.placeholderShownTargets inputs or textareas showing their placeholder.Style input fields with visible placeholders.
ps.playingTargets playing media elements.Style active video or audio players.
ps.popoverOpenTargets open popover elements.Style open popovers.
ps.readOnlyTargets read-only form elements.Style read-only inputs.
ps.readWriteTargets editable form elements.Style editable textareas.
ps.requiredTargets required form elements.Highlight required input fields.
ps.rightTargets elements in a paged context (e.g., print layouts).Style right-hand pages in a print stylesheet.
ps.rootTargets the root element of a document or shadow DOM.Style the <html> or shadow DOM root.
ps.scopeTargets elements within a specific scope (e.g., :scope).Style elements in a specific context.
ps.seekingTargets media elements during seeking.Style a video player during seek operations.
ps.stalledTargets media elements that are stalled.Style stalled media players.
ps.targetTargets an element that is the target of a URL fragment.Style the element with a matching id in the URL.
ps.userInvalidTargets form elements marked invalid by user interaction.Style inputs after user error.
ps.userValidTargets form elements marked valid by user interaction.Style inputs after successful validation.
ps.validTargets valid form elements.Style valid input fields.
ps.visitedTargets visited links.Style visited <a> tags.
ps.volumeLockedTargets media elements with locked volume controls.Style media players with restricted volume.

Pseudo-Elements

Pseudo-elements allow styling specific parts of an element, such as its first letter or content inserted before/after it.

Pseudo-ElementDescriptionExample Use Case
ps.afterStyles content inserted after an element.Add an icon after a link.
ps.backdropTargets the backdrop of a dialog or fullscreen element.Style the dimmed background of a modal.
ps.beforeStyles content inserted before an element.Add a bullet before a list item.
ps.cueStyles WebVTT cues for media elements (e.g., subtitles).Customize subtitle appearance in videos.
ps.detailsContentTargets the content of a <details> element.Style the content inside an accordion.
ps.firstSelectorButtonTargets the first selector button in a UI component.Style the first button in a custom form control.
ps.firstLetterStyles the first letter of an element’s text.Enlarge the first letter of a paragraph.
ps.firstLineStyles the first line of an element’s text.Bold the first line of a paragraph.
ps.grammarErrorStyles text marked as a grammar error by the browser.Highlight grammar errors in a text editor.
ps.markerStyles list item markers (e.g., bullets or numbers).Customize bullet styles in a list.
ps.placeholderStyles the placeholder text in inputs or textareas.Change placeholder text color.
ps.selectionStyles selected text within an element.Customize text selection highlight.
ps.spellingErrorStyles text marked as a spelling error by the browser.Highlight spelling errors in a text editor.
ps.targetTextStyles text targeted by a URL fragment.Highlight text linked via a URL anchor.
ps.viewTransitionStyles elements during a view transition animation.Style elements during page transitions.

Functional Pseudo-Classes

Functional pseudo-classes accept arguments to define complex selectors dynamically.

Functional Pseudo-ClassDescriptionExample Use Case
ps.fn.dir(direction)Targets elements based on text direction (e.g., ltr or rtl).Style text differently for RTL languages.
ps.fn.has(selector)Matches elements containing specific descendants.Style a <div> containing a specific <span>.
ps.fn.host(selector)Targets the shadow DOM host matching the selector.Style a shadow DOM host based on a class.
ps.fn.hostContext(selector)Matches the shadow DOM host based on its context.Style a host when a parent has a specific class.
ps.fn.is(selector)Matches elements that match any of the provided selectors.Combine multiple selectors for flexible styling.
ps.fn.lang(language)Targets elements with a specific language (e.g., en, ja).Style text for a specific language.
ps.fn.nthChild(formula)Targets elements based on their position among siblings (e.g., 2n+1).Style odd-numbered list items.
ps.fn.nthLastChild(formula)Targets elements based on their position from the last sibling.Style the second-to-last list item.
ps.fn.nthLastOfType(formula)Targets elements of a type based on their position from the last sibling.Style the last <p> among siblings.
ps.fn.nthOfType(formula)Targets elements of a type based on their position among siblings.Style every third <div> of its type.
ps.fn.not(selector)Targets elements that do not match the provided selector.Style all elements except those with a specific class.
ps.fn.state(state)Targets elements in a specific custom state.Style elements with a custom state attribute.
ps.fn.where(selector)Matches elements that match the provided selector with specificity.Style elements matching complex conditions.

Functional Pseudo-Elements

Functional pseudo-elements allow styling specific parts of an element with arguments.

Functional Pseudo-ElementDescriptionExample Use Case
ps.fn.cue(selector)Styles specific WebVTT cues for media elements.Customize specific subtitle styles in videos.
ps.fn.highlight(name)Styles highlighted content (e.g., search results).Highlight search matches in a document.
ps.fn.part(name)Targets a specific part in a shadow DOM.Style a specific part of a custom component.
ps.fn.slotted(selector)Styles slotted content in a shadow DOM.Style content passed into a shadow DOM slot.
ps.fn.viewTransitionGroup(name)Styles a group of elements during a view transition.Style a group during page transitions.
ps.fn.viewTransitionImagePair(name)Styles an image pair during a view transition.Style images during a transition animation.
ps.fn.viewTransitionNew(name)Styles the new content during a view transition.Style incoming content in a transition.
ps.fn.viewTransitionOld(name)Styles the old content during a view transition.Style outgoing content in a transition.

Usage Examples

Below are practical examples demonstrating how to use the pseudo utility with @plumeria/core.

Example 1: Styling a Button with Hover and Focus

TypeScript Example
import { css, ps } from '@plumeria/core';
 
const buttonStyles = css.create({
  button: {
    background: 'blue',
    color: 'white',
    padding: '10px 20px',
    [ps.hover]: {
      background: 'darkblue',
    },
    [ps.focus]: {
      outline: '2px solid yellow',
    },
  },
});

Example 2: Combining Pseudo-Classes with px

import { px } from '@plumeria/core';
 
const combinedStyles = px(ps.active, ps.focusVisible, ps.fn.has('div'));

Example 3: Using Functional Pseudo-Classes

import { css, ps } from '@plumeria/core';
 
const listStyles = css.create({
  list: {
    [ps.fn.nthChild('2n')]: {
      background: 'lightgray',
    },
    [ps.fn.has('img')]: {
      border: '1px solid black',
    },
  },
});

Example 4: Styling Pseudo-Elements

import { css, ps } from '@plumeria/core';
 
const textStyles = css.create({
  text: {
    [ps.firstLetter]: {
      fontSize: '1.5em',
      color: 'red',
    },
    [ps.before]: {
      content: '"★ "',
      color: 'gold',
    },
  },
});
;