cascadia library

Classes

AnyLinkPseudoClass

:any-link — any element with an href.

AttributeSelector

An attribute selector such as [href^="https"].

CheckedPseudoClass

:checked — a checked checkbox/radio or a selected option.

ClassSelector

A class selector such as .warning.

CombinedSelector

Two selectors joined by a combinator, e.g. div > p.

CompoundSelector

Several simple selectors applied to the same element, e.g. div.foo#bar.

ContainsPseudoClass

:contains(text) / :containsown(text) — non-standard text search.

DefaultPseudoClass

:default — the default control within a form.

DefinedPseudoClass

:defined — a built-in element, or a registered custom element.

DirPseudoClass

:dir(ltr|rtl) — matches an element's resolved text direction.

DisabledPseudoClass

:disabled — a form control that is disabled.

EmptyPseudoClass

:empty — no element children and no non-whitespace text.

EnabledPseudoClass

:enabled — a form control that is not disabled.

FullscreenPseudoClass

:fullscreen — an element currently rendered fullscreen.

HasChildPseudoClass

:haschild(...) — non-standard; matches elements with a matching child.

HasPseudoClass

:has(...) — matches elements with a relative selector match.

HasSlottedPseudoClass

:has-slotted(selector?) — a <slot> with assigned content.

HeadingPseudoClass

:heading and :heading(an+b) — non-standard heading selector.

HostContextPseudoClass

:host-context(selector) — the host, when an ancestor matches.

HostPseudoClass

:host, and :host(selector) when selector is supplied.

IdSelector

An ID selector such as #header.

IndeterminatePseudoClass

:indeterminate — requires runtime state supplied via MatchContext.

InputPseudoClass

:input — non-standard; any form control.

InteractionPseudoClass

A user-interaction state selector: :hover, :focus, :active and kin.

IsPseudoClass

:is(...) — matches elements matching any argument selector.

LangPseudoClass

:lang(tag) — matches the element's language, inherited from ancestors.

LinkPseudoClass

:link — a link that has not been visited.

LocalLinkPseudoClass

:local-link — a link pointing at the current document's URL.

MatchContext

Runtime facts a caller can supply so that otherwise-undecidable selectors can be evaluated.

MatchesPseudoClass

:matches(/re/) / :matchesown(/re/) — non-standard regex text search.

MediaStatePseudoClass

A media-element state selector such as :muted or :playing.

ModalPseudoClass

:modal — an element blocking interaction with the rest of the page.

NestingSelector

The CSS nesting selector &.

NotPseudoClass

:not(...) — matches elements that match none of the argument selectors.

NthPseudoClass

:nth-child(), :nth-last-child(), :nth-of-type(), :nth-last-of-type() and their :first-/:last- shorthands.

OnlyChildPseudoClass

:only-child and :only-of-type.

OpenPseudoClass

:open — an open <details> or <dialog>.

Parser

Parses CSS selector text into Sel objects.

PlaceholderShownPseudoClass

:placeholder-shown — a control displaying its placeholder text.

PopoverOpenPseudoClass

:popover-open — a popover currently being shown.

PseudoClassSelector

Base class for pseudo-class selectors. Defaults to (0,1,0) specificity.

PseudoElementSelector

A pseudo-element such as ::before or ::part(header).

ReadOnlyPseudoClass

:read-only and :read-write.

RelativeSelector

A selector with a leading combinator, used inside :has().

RequiredPseudoClass

:required and :optional.

RootPseudoClass

:root — the document's root element.

ScopePseudoClass

:scope — the reference element of a scoped query.

Sel

A CSS selector that can be matched against a DOM node.

SelectorGroup

A comma-separated selector list; matches when any component matches.

Specificity

CSS selector specificity as a triple (a, b, c):

StatePseudoClass

:state(name) — a custom element's internal state.

TagSelector

A type selector such as div, or svg|rect when namespace-qualified.

TargetPseudoClass

:target — the element referenced by the URL fragment.

TargetWithinPseudoClass

:target-within — an element containing (or being) the fragment target.

TextContent

Text extraction helpers shared by :contains() and :matches().

UndecidablePseudoClass

A pseudo-class whose result depends on runtime state the caller may supply.

UniversalSelector

The universal selector *.

UnknownPseudoClass

A pseudo-class this library does not recognise.

VisitedPseudoClass

:visited — a link the user has visited.

WherePseudoClass

:where(...) — like :is() but always contributes zero specificity.

Enums

AttrOp

The operators supported by AttributeSelector.

MatchSupport

How well a selector can be evaluated against a static DOM.

Extensions

ElementTagName on Element

A lowercased tagName alias for Element.localName.

SelAdapter on Sel

Adapts a Sel to a plain Selector function.

Constants

defaultNamespaces → const Map<String, String>

Well-known namespace URIs, used to resolve namespace prefixes.

formControlTags → const Set<String>

Elements that :enabled/:disabled may apply to.

knownPseudoElements → const Map<String, String>

Pseudo-elements recognised by this library, and whether each takes an argument (required, optional or none).

Properties

selectorCacheSize → int

The number of selectors currently cached. Exposed for tests and tuning.

no setter

Functions

anBMatches(int a, int b, int position) → bool

Whether a 1-based position satisfies an+b.

clearSelectorCache() → void

Removes every entry from the parsed-selector cache.

closest(Node node, String selector, [MatchContext context = MatchContext.empty]) → Element?

Returns the closest inclusive ancestor of node matching selector.

compile(String selector) → Selector

Compiles selector into a predicate function.

escapeCssIdent(String value) → String

Escapes value so it can be emitted as a CSS identifier.

escapeCssString(String value) → String

Escapes value and wraps it in double quotes for use as a CSS string.

formatAnB(int a, int b) → String

Formats an an+b expression in canonical CSS form.

matches(Node node, String selector, [MatchContext context = MatchContext.empty]) → bool

Whether node matches selector.

namespaceMatches(Element element, String? prefix) → bool

Whether element satisfies the namespace constraint prefix.

parse(String selector) → Sel

Parses selector into a reusable Sel.

parseGroup(String selector) → Sel

Parses selector, which may be a comma-separated list.

parseLenient(String selector) → Sel

Parses selector, tolerating pseudo-classes this library does not know.

parseWithPseudoElements(String selector) → Sel

Parses selector with pseudo-elements such as ::before permitted.

query(Node root, String selector, [MatchContext context = MatchContext.empty]) → Element?

Returns the first descendant of root matching selector, or null.

queryAll(Node root, String selector, [MatchContext context = MatchContext.empty]) → List<Element>

Returns every descendant of root matching selector.

serialize(Sel sel) → String

Serializes sel back to CSS text.

Typedefs

Selector = bool Function(Node)

A function that tests whether a node matches a selector.

Exceptions / Errors

UndecidableSelectorError

Thrown when a selector cannot be decided and MatchContext.strict is set.