All Collections
Using the Mutiny Experience Editor
How the Mutiny editor selects elements
How the Mutiny editor selects elements

Understanding how the Mutiny editor selects elements can help you ensure your personalizations always target the right element.

Updated over a week ago

The Mutiny editor makes it easy to select elements on your site so that you can update and personalize content for your users. This doc will lay out the technicalities of how we select elements in the editor, as well provide strategies for updating your website to make this process easier.

CSS selectors

Before we dive into the specifics of Mutiny, its important to understand the concept of CSS selectors. CSS selectors are simply patterns that we use to select elements on a webpage. Take this bit of code for example:

<div id="intro" class="centered">This is my intro.</div>

There are a few ways we can use CSS selectors to select this element. First, because the <div> element is the only element noted here, we could simply use div as our selector. However, its rare for any webpage to just have one <div> element on the page, so if we just used div we probably wouldn’t know which div we wanted to select.

To get around this, we can use other parts of an element (like ids and classes) to select elements more specifically. For example, we could use the selector of div.centered. Using a ‘.’ indicates that we want a div with the class of centered. Again, this works here, but what if you have other divs that are centered using the class of centered? We may have to get even more specific.

Luckily in this case, we can use an ID to select an element. The nice thing about ids is they’re always unique to a page, in that this page will only have one id of intro. So if we use a selector of div#intro, we know we’ll be selecting this (and only) this div element.

There are lots of ways we can use CSS selectors to select specific elements and we encourage you to take a look at the W3Schools CSS selectors tester to play around with different selectors.

How Mutiny selects elements

Mutiny uses CSS selectors to identify elements that you click on when working in the visual editor. Just as we saw in the example above, we want to make sure that we identify elements uniquely so that when you update an element, we know exactly which element is being updated.

To do this, we use a hierarchical method of selection. When you click on an element, we’re going to check the following selectors in this order to see if we get a unique selector.

  1. ID

  2. Class

  3. Tag

  4. nth-of-type

If we go through this list and aren’t able to find a unique selector, we’ll move up the DOM one step and do the same thing. We’ll do this repeatedly until we eventually find a unique selector. Lets see this in an example.

<div id="intro" class="centered"> 
<p class="centered">I have something to say".</p>
<p class="centered">
<a href="<https://google.com>">I have something to say but this time I want to have it in a link".</a>
</p>
</div>
<div class="centered">
<p class="centered">This is the text that I'd like to personalize.</p> </div>

Lets imagine you want to personalize the text that says “This is the text that I’d like to personalize”. If you selected that element, Mutiny would first look for an ID on that element. There isn’t one. We’d then look for a class. There is a class, but its not unique (there are a number of elements with the class of centered). We’d then move up to the tag of <p>, and find that thats not unique either. We then use nth-of-type, and decide to move up the DOM. We go through the same process on the <div> element and unfortunately, there isn’t much unique about this. So we end up with a final selector of div:nth-of-type(2) > p . This essentially means “give me the second div, and then the p tag under it. Here we have a unique selector.

Nth-of-type issue

We’ve talked about the nth-of-type method of selecting elements, but its important to understand why this method may be problematic. In the example above, we were only able to get to a unique selector by using nth-of-type. This is because the second <div> element didn’t have any other unique properties to it (it didn’t have an id and the class of centered was also used on the <div> above it). The problem with nth-of-type is that it can sometimes be unreliable.

Lets continue with the example above. Imagine we showed this webpage to a user, but because they were based in Europe, we had to include a cookie consent banner on the page, so now the page HTML actually looks like this:

<div id="intro" class="centered"> 
<p class="centered">I have something to say".</p>
<p class="centered">
<a href="<https://google.com>">I have something to say but this time I want to have it in a link".</a>
</p>
</div>
<div class=cookie-consent>
<p class="centered">Do you accept cookies?</p>
</div>
<div class="centered">
<p class="centered">This is the text that I'd like to personalize.</p> </div>

Do you see what happened here? The <div> that we actually want to personalize is no longer the second <div> on the page. If we made changes based on our original selector of div:nth-of-type(2) > p we’d now be making updates to our cookie consent text instead. This is an nth-of-type issue.

Its important to note here that nth-of-type selectors are not always a bad option, especially when they’re paired with other, more reliable selectors. For example, if we wanted to select the link in the HTML above, we could use a selector of div#intro > p:nth-of-type(2) > a. We’re using an nth-of-type selector, but its paired with the id from the div above it which means we’re much less likely to run into an nth-of-type issue.

Selector recommendations

To help avoid this issue and to make your selectors more reliable for Mutiny to select elements, we recommend doing these things.

  1. Add IDs to your page sections. IDs are the most reliable selector and having them at least on the different sections of your page will help you gain a good level of specificity.

  2. Identify the elements you’ll want to personalize often and make sure they are easily identifiable. For example, if you foresee always wanting to update your logo-bar, make sure that that element has some distinction from other elements on the page.

  3. If you have sections on your page with multiple of the same elements in a row, it can often be helpful to number them with classes or ids. For example, if you have a section that looks like this, you may want to identify these as <div class="card-1"> and <div class="card-2">. You may also choose to identify these elements based on their content (i.e. <div class="architect-card">

  4. If you use dynamic class names on your site, you may want to add in more static selectors to help with personalization. More information on how Mutiny handles dynamic selectors can be found here.

  5. Finally, don’t be afraid of our “Find Element” feature. Sometimes, you can find a better CSS selector than we can ;).


Don't be a stranger

If you have any questions, we’re here to help! Please feel free to contact us at any time via support@mutinyhq.com.

Did this answer your question?