DOMTokenList item() Method: Getting Token by Index

Table of Contents

DOMTokenList `item()` Method: Getting Tokens by Index

The item() method of the DOMTokenList interface is used to retrieve a token from the list by its index. This method is particularly useful when you need to access a specific token based on its position within the list of tokens. This guide provides a detailed explanation of the item() method, its syntax, and practical examples to illustrate its usage.

What is the `DOMTokenList` `item()` Method?

The item() method returns the token at the specified index in the DOMTokenList. The index is zero-based, meaning the first token is at index 0, the second at index 1, and so on. If the index is out of bounds (i.e., greater than or equal to the length of the list), the method returns null.

Purpose of the `item()` Method

The primary purpose of the item() method is to provide indexed access to the tokens within a DOMTokenList. This is essential when you need to programmatically access tokens based on their position, such as in loops or when handling specific tokens in a predefined order.

Syntax

The syntax for using the item() method is straightforward:

let token = domTokenList.item(index);

index: An integer representing the index of the token to retrieve.

Return Value

Returns the token at the specified index as a string.
Returns null if the index is out of bounds.

Examples

Let’s explore several examples to illustrate how to use the item() method effectively.

Basic Example: Accessing a Token by Index

This example demonstrates how to access a token in a DOMTokenList using its index.

<div id="myElement" class="token1 token2 token3"></div>

<script>
  const element_item_basic = document.getElementById("myElement");
  const classList_item_basic = element_item_basic.classList;

  const firstToken_item_basic = classList_item_basic.item(0);
  const secondToken_item_basic = classList_item_basic.item(1);
  const thirdToken_item_basic = classList_item_basic.item(2);

  console.log("First token:", firstToken_item_basic); // Output: First token: token1
  console.log("Second token:", secondToken_item_basic); // Output: Second token: token2
  console.log("Third token:", thirdToken_item_basic); // Output: Third token: token3
</script>

In this example, we retrieve the first, second, and third tokens from the classList of the myElement div using their respective indices (0, 1, and 2).

Handling Out-of-Bounds Indices

This example shows how the item() method returns null when the index is out of bounds.

<div id="myElementOutOfBounds" class="tokenA tokenB"></div>

<script>
  const element_item_oob = document.getElementById("myElementOutOfBounds");
  const classList_item_oob = element_item_oob.classList;

  const tokenAtIndex2_item_oob = classList_item_oob.item(2);
  console.log("Token at index 2:", tokenAtIndex2_item_oob); // Output: Token at index 2: null
</script>

Here, we attempt to access the token at index 2, but since the DOMTokenList only contains two tokens (at indices 0 and 1), the method returns null.

Using `item()` in a Loop

This example demonstrates how to use the item() method within a loop to iterate through all tokens in a DOMTokenList.

<div id="myElementLoop" class="item1 item2 item3 item4"></div>

<script>
  const element_item_loop = document.getElementById("myElementLoop");
  const classList_item_loop = element_item_loop.classList;

  for (let i = 0; i < classList_item_loop.length; i++) {
    const token_item_loop = classList_item_loop.item(i);
    console.log(`Token at index ${i}:`, token_item_loop);
  }
  // Output:
  // Token at index 0: item1
  // Token at index 1: item2
  // Token at index 2: item3
  // Token at index 3: item4
</script>

In this example, we loop through the classList of the myElementLoop div and print each token along with its index.

Real-World Use Case: Dynamic Styling Based on Token Index

This example demonstrates a practical use case where the item() method is used to apply dynamic styling based on the index of tokens in a DOMTokenList.

<div id="myElementStyle" class="color-1 color-2 color-3"></div>

<style>
  .color-1 {
    color: red;
  }
  .color-2 {
    color: green;
  }
  .color-3 {
    color: blue;
  }
</style>

<script>
  const element_item_style = document.getElementById("myElementStyle");
  const classList_item_style = element_item_style.classList;

  for (let i = 0; i < classList_item_style.length; i++) {
    const token_item_style = classList_item_style.item(i);
    console.log(`Token at index ${i}:`, token_item_style);
  }
</script>

In this scenario, the CSS classes color-1, color-2, and color-3 define different text colors. The script iterates through the class list and logs the tokens, which, in turn, apply the corresponding styles to the element.

Tips and Best Practices

Check for null: Always check if the item() method returns null when accessing tokens by index, especially when the index might be out of bounds.
Use Loops Carefully: When using item() in loops, ensure the loop condition correctly reflects the length of the DOMTokenList to avoid errors.
Consider Alternatives: For simple cases, consider using other methods like contains(), add(), remove(), or toggle() if you don’t need to access tokens by index.

Conclusion

The item() method of the DOMTokenList interface is a valuable tool for accessing tokens by their index. This guide provided a detailed explanation of the method, its syntax, and practical examples to illustrate its usage. By understanding how to use the item() method effectively, you can programmatically access tokens based on their position, enabling dynamic manipulation and styling of HTML elements.