Pseudo Utility

Comprehensive API reference for the `pseudo` utility in the zss-utils package, covering all pseudo-classes, pseudo-elements, and functional pseudo selectors.

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-Class	Description	Example Use Case
`ps.active`	Styles an element when it is being activated (e.g., clicked).	Highlight a button during a click event.
`ps.anyLink`	Targets any link, whether visited or unvisited.	Style all anchor tags uniformly.
`ps.autoFill`	Targets form elements auto-filled by the browser.	Customize the appearance of auto-filled input fields.
`ps.buffering`	Styles media elements (e.g., `<video>`) while buffering.	Display a loading state for a video player.
`ps.checked`	Targets checked form elements (e.g., checkboxes, radio buttons).	Style checked radio buttons or checkboxes.
`ps.default`	Targets the default element among a group (e.g., default button in a form).	Highlight the default submit button.
`ps.defined`	Targets elements that are defined (e.g., custom elements with a definition).	Style custom web components after definition.
`ps.disabled`	Targets disabled form elements or controls.	Gray out disabled buttons or inputs.
`ps.empty`	Targets elements with no children or text content.	Hide empty `<div>` elements.
`ps.enabled`	Targets enabled form elements or controls.	Style enabled inputs differently from disabled ones.
`ps.first`	Targets the first element in a group (e.g., in a `:where()` context).	Style the first item in a dynamic list.
`ps.firstChild`	Targets the first child of a parent element.	Style the first `<p>` in a `<div>`.
`ps.firstOfType`	Targets the first sibling of its type.	Style the first `<h1>` among siblings.
`ps.focus`	Targets an element that has focus (e.g., via keyboard or click).	Add an outline to focused input fields.
`ps.focusVisible`	Targets an element with visible focus (e.g., keyboard navigation).	Show focus ring only for keyboard users.
`ps.focusWithin`	Targets an element containing a focused descendant.	Style a form when any input inside is focused.
`ps.fullscreen`	Targets an element in fullscreen mode.	Style a video player in fullscreen.
`ps.future`	Targets elements in a timeline context (e.g., Temporal API).	Style future dates in a calendar.
`ps.hasSlotted`	Targets shadow DOM hosts with slotted content.	Style elements with slotted children in shadow DOM.
`ps.host`	Targets the shadow DOM host element.	Style the root of a shadow DOM.
`ps.hover`	Styles an element when the mouse hovers over it.	Change background color on hover.
`ps.inRange`	Targets form elements with values within a valid range.	Highlight valid range inputs.
`ps.indeterminate`	Targets checkboxes or radio buttons in an indeterminate state.	Style indeterminate checkboxes.
`ps.invalid`	Targets form elements with invalid input.	Highlight invalid input fields.
`ps.lastChild`	Targets the last child of a parent element.	Style the last `<li>` in a list.
`ps.lastOfType`	Targets the last sibling of its type.	Style the last `<p>` among siblings.
`ps.left`	Targets elements in a paged context (e.g., print layouts).	Style left-hand pages in a print stylesheet.
`ps.link`	Targets unvisited links.	Style unvisited `<a>` tags.
`ps.modal`	Targets elements in a modal state (e.g., dialogs).	Style modal dialogs.
`ps.muted`	Targets media elements that are muted.	Style muted video players.
`ps.onlyChild`	Targets an element that is the only child of its parent.	Style a lone `<span>` in a `<div>`.
`ps.onlyOfType`	Targets an element that is the only one of its type among siblings.	Style a single `<h2>` among siblings.
`ps.open`	Targets open `<details>` or `<dialog>` elements.	Style open accordion sections.
`ps.optional`	Targets form elements that are not required.	Style optional input fields.
`ps.outOfRange`	Targets form elements with values outside a valid range.	Highlight out-of-range inputs.
`ps.past`	Targets elements in a timeline context (e.g., Temporal API).	Style past dates in a calendar.
`ps.paused`	Targets paused media elements.	Style paused video players.
`ps.pictureInPicture`	Targets elements in picture-in-picture mode.	Style videos in PIP mode.
`ps.placeholderShown`	Targets inputs or textareas showing their placeholder.	Style input fields with visible placeholders.
`ps.playing`	Targets playing media elements.	Style active video or audio players.
`ps.popoverOpen`	Targets open popover elements.	Style open popovers.
`ps.readOnly`	Targets read-only form elements.	Style read-only inputs.
`ps.readWrite`	Targets editable form elements.	Style editable textareas.
`ps.required`	Targets required form elements.	Highlight required input fields.
`ps.right`	Targets elements in a paged context (e.g., print layouts).	Style right-hand pages in a print stylesheet.
`ps.root`	Targets the root element of a document or shadow DOM.	Style the `<html>` or shadow DOM root.
`ps.scope`	Targets elements within a specific scope (e.g., `:scope`).	Style elements in a specific context.
`ps.seeking`	Targets media elements during seeking.	Style a video player during seek operations.
`ps.stalled`	Targets media elements that are stalled.	Style stalled media players.
`ps.target`	Targets an element that is the target of a URL fragment.	Style the element with a matching `id` in the URL.
`ps.userInvalid`	Targets form elements marked invalid by user interaction.	Style inputs after user error.
`ps.userValid`	Targets form elements marked valid by user interaction.	Style inputs after successful validation.
`ps.valid`	Targets valid form elements.	Style valid input fields.
`ps.visited`	Targets visited links.	Style visited `<a>` tags.
`ps.volumeLocked`	Targets 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-Element	Description	Example Use Case
`ps.after`	Styles content inserted after an element.	Add an icon after a link.
`ps.backdrop`	Targets the backdrop of a dialog or fullscreen element.	Style the dimmed background of a modal.
`ps.before`	Styles content inserted before an element.	Add a bullet before a list item.
`ps.cue`	Styles WebVTT cues for media elements (e.g., subtitles).	Customize subtitle appearance in videos.
`ps.detailsContent`	Targets the content of a `<details>` element.	Style the content inside an accordion.
`ps.firstSelectorButton`	Targets the first selector button in a UI component.	Style the first button in a custom form control.
`ps.firstLetter`	Styles the first letter of an element’s text.	Enlarge the first letter of a paragraph.
`ps.firstLine`	Styles the first line of an element’s text.	Bold the first line of a paragraph.
`ps.grammarError`	Styles text marked as a grammar error by the browser.	Highlight grammar errors in a text editor.
`ps.marker`	Styles list item markers (e.g., bullets or numbers).	Customize bullet styles in a list.
`ps.placeholder`	Styles the placeholder text in inputs or textareas.	Change placeholder text color.
`ps.selection`	Styles selected text within an element.	Customize text selection highlight.
`ps.spellingError`	Styles text marked as a spelling error by the browser.	Highlight spelling errors in a text editor.
`ps.targetText`	Styles text targeted by a URL fragment.	Highlight text linked via a URL anchor.
`ps.viewTransition`	Styles 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-Class	Description	Example 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-Element	Description	Example 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',
    },
  },
});

zss-utils Package

Explore other utilities in the zss-utils package.

Plumeria Core Documentation

Learn more about the @plumeria/core package.

Pseudo Utility

zss-utils Package

Plumeria Core Documentation

On this page