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
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
.