How it works?

The $.select() function is fundamental to element related DOM modification. This function has the ability to select elements with a CSS style.

This function will accept a string to select one or multiple elements.
Here is a little help on basic CSS selectors (thanks to Mozilla for this part):

Basic Selectors

Type selectors

This basic selector chooses all elements that match the given name.
Syntax: eltname
Example: input will match any <input> element.

Class selectors

This basic selector chooses elements based on the value of their class attribute.
Syntax: .classname
Example: .index will match any element that has the class index (likely defined by a class="index" attribute or similar).

ID selectors

This basic selector chooses nodes based on the value of its id attribute. There should be only one element with a given ID in a document.
Syntax: #idname
Example: #toc will match the element that has the id toc (likely defined by a id="toc" attribute or similar).

Universal selectors

This basic selector chooses all nodes. It also exists in a one-namespace only and in an all-namespace variant too.
Syntax: * ns|* *|*
Example: * will match all the elements of the document.

Attribute selectors

This basic selector chooses nodes based on the value of one of its attributes.
Syntax: [attr] [attr=value] [attr~=value] [attr|=value] [attr^=value] [attr$=value] [attr*=value]
Example: [autoplay] will match all the elements that have the autoplay attribute set (to any value).

Combinators

Adjacent sibling selectors

The '+' combinator selects nodes that immediately follow the former specified element.
Syntax: A + B
Example: div + p will match any <p> that immediately follows a <div>.

General sibling selectors

The '~' combinator selects nodes that follow (not necessarily immediately) the former specified element, if both elements shared the same parent.
Syntax: A ~ B
Example: p ~ span will match all <span> elements that follow a <p> element inside the same element.

Child selectors

The '>' combinator selects nodes that are direct children of the former specified element.
Syntax: A > B
Example: ul > li will match all <li> elements that are inside a <ul> element.

Descendant selectors

The ' ' combinator selects nodes that are children (not necessary direct children) of the former specified element.
Syntax: A B
Example: div span will match any <span> element that is inside a <div> element.

Pseudo-elements

Pseudo-elements are abstractions of the tree representing entities beyond what HTML does. For example, HTML doesn't have an element describing the first letter or line of a paragraph, or the marker of a list. Pseudo-elements represent these entities and allow CSS rules to be associated with them. that way, these entitities can be styled independently.

Pseudo-classes

Pseudo-classes allow selecting elements based on information that is not contained in the document tree like a state or that is particularly complex to extract. E.g. they match if a link has been previously visited or not.

How to use it?

This function will return you an array of elements, so have to use it in another DisplayJS function.
⚠️ Do not use this function outside a DisplayJS function. By the way, in each DisplayJS function, it will always select only the first element. If you to apply the function to every elements, go see the $.all() function.
Let's say you want to display text in an element, in particular, let's say that it's an element with the class myElement. That's how we do:

HTML

<div class="myElement></div>

JS:

// Creating the $ variable for DisplayJS. Remember this, because I won't always put that line, further in the docs, I'll assume that you know that 😊.
var $ = new DisplayJS(window);
// selecting the element and give it some text
$.text($.select(".myElement"), "Hello World 🌎")

$.single()

This function is exactly like the $.select() function, but will only return one element, instead of a list, which is way more interesting if you want to use your own functions.
⚠️ Do not use it with DisplayJS functions, it simply won't work. This function is only there for people who wants to use their own functions

Example

Let's take the situation above. We'll do the same thing but without the text function.

JS:

$.single(".myElement").innerHTML = "Hello world 🌎!";

⚠️ Questions?

Don't hesitate to ask your questions ⁉️ in the issue part 😁