X/Twitter DOM Selector Reference

Last verified: February 2026. Twitter frequently changes their DOM — always verify selectors before use.

This is the canonical reference for all known X/Twitter DOM selectors used across the XActions project. Check here before writing new selectors.

UserCell Elements

Search results, followers lists, following lists, and any user-list UI.

Profile Page Elements

Selectors for profile pages (x.com/username).

Tweet Elements

Tweet/post containers, content, and metadata.

Engagement Buttons

Like, reply, retweet, bookmark, share, and analytics buttons on tweets.

Follow / Unfollow

Compose / Post Creation

Compose Toolbar

Scheduling

Poll Elements

Profile Editing

Navigation / Layout

Search / Explore

Direct Messages

Block / Mute / Report

Notifications

Bookmarks

Lists

Communities

Spaces / Live Audio

Grok AI

Articles / Longform

Creator Studio / Monetization

Settings / Privacy

Dialogs / Confirmations

Generic / Utility

Selectors used across many contexts as fallbacks or for text extraction.

Common Pitfalls

Case Sensitivity

data-testid values are CASE-SENSITIVE:

• ✅ UserDescription (capital U, capital D)
• ❌ userdescription
• ✅ User-Name (capital U, capital N, with hyphen)
• ❌ user-name
• ⚠️ UserName on profile pages vs User-Name in tweets — they are different selectors

Suffix Matchers for Follow/Unfollow

Follow/unfollow buttons include a username prefix in their data-testid:

data-testid="nichxbt-follow"
data-testid="nichxbt-unfollow"

Always use the suffix match ($=):

// ✅ Correct
document.querySelector('[data-testid$="-follow"]');

// ❌ Wrong — won't match
document.querySelector('[data-testid="follow"]');

Bio vs Display Name in UserCells

Multiple [dir="auto"] elements exist inside a UserCell. To find the bio:

// ✅ Best approach — use data-testid
cell.querySelector('[data-testid="UserDescription"]');

// ⚠️ Fallback — filter out elements inside links
const bioEl = [...cell.querySelectorAll('[dir="auto"]')]
  .filter(el => !el.closest('a') && !el.closest('[data-testid="User-Name"]'))
  .pop();

Navigation Breaks Scripts

Browser console scripts stop when the page navigates. Use sessionStorage to persist state:

const getProcessed = () => {
  try { return JSON.parse(sessionStorage.getItem('xactions_key') || '[]'); }
  catch { return []; }
};

Confirmation Dialogs Are Required

Many destructive actions pop up a confirmation dialog. Always wait for and click it:

await sleep(500);
const confirm = document.querySelector('[data-testid="confirmationSheetConfirm"]');
if (confirm) confirm.click();

Promoted Content Filtering

Filter out ads before processing tweets:

const isAd = tweet.closest('[data-testid="placementTracking"]');
if (isAd) continue;

Rate Limiting

Add delays between actions (1–3 seconds minimum). X will temporarily restrict your account if you bulk-act too fast.

DOM Changes

X/Twitter frequently updates their DOM. If a selector stops working:

1. Check the browser DevTools for the current data-testid
2. Look for aria-label alternatives
3. Fall back to structural selectors (role, tag hierarchy)
4. Update this document

Selector Architecture

The XActions codebase uses a fallback chain pattern for resilient selector matching.

Canonical Source Files

Fallback Chain Pattern

// From src/utils/core.js — the canonical pattern
const SELECTORS = {
  tweet: [
    'article[data-testid="tweet"]',       // Primary: data-testid
    'article[role="article"]',             // Fallback 1: role
    '[data-testid="cellInnerDiv"] article' // Fallback 2: structural
  ],
  tweetText: [
    '[data-testid="tweetText"]',   // Primary
    '[lang][dir] span',            // Fallback 1
    'article span[dir="auto"]'     // Fallback 2
  ]
};

When writing new selectors:

1. Primary: Use data-testid when available
2. Fallback 1: Use aria-label or role attributes
3. Fallback 2: Use structural/positional selectors as last resort
4. Always add new selectors to this document

Contributing: When you discover a new selector or a changed one, update this file and the SELECTORS object in src/utils/core.js. Keep this document as the single source of truth.