twitter-trends-ui

A lightweight, framework-agnostic UI library for displaying Twitter/X trending topics.

Live Demo: https://twitterviewer.xyz - View Twitter trends without logging in!

Features

• TrendsUI - Main component for displaying trending topics with optional AI summaries
• FloatingTags - Animated floating tags showing popular trends
• Timeline - Horizontal scrollable timeline showing historical trend data
• Zero dependencies (vanilla JavaScript)
• TypeScript support
• Works with any framework (React, Vue, Angular, etc.) or vanilla JS

Installation

npm install twitter-trends-ui

Quick Start

Browser (UMD)

<script src="https://unpkg.com/twitter-trends-ui/dist/index.umd.min.js"></script>
<script>
  const { TrendsUI } = TwitterTrendsUI;

  const trends = new TrendsUI({
    container: '#trends-container'
  });

  trends.render({
    location: 'Worldwide',
    trends: [
      { name: '#JavaScript', url: 'https://x.com/search?q=%23JavaScript', rank: 1, tweet_volume: 125000 },
      { name: 'TypeScript', url: 'https://x.com/search?q=TypeScript', rank: 2, tweet_volume: 89000 }
    ]
  });
</script>

ES Modules

import { TrendsUI, FloatingTags, Timeline } from 'twitter-trends-ui';

const trends = new TrendsUI({
  container: document.getElementById('trends'),
  showSummaries: true,
  onTrendClick: (trend, index) => {
    console.log('Clicked:', trend.name);
  }
});

trends.render(data);

Components

TrendsUI

The main component for displaying a list of trending topics.

const trends = new TrendsUI({
  container: '#trends',           // Required: container element or selector
  showRank: true,                 // Show rank numbers (default: true)
  showVolume: true,               // Show tweet volume (default: true)
  showSummaries: true,            // Show AI summaries (default: true)
  summariesCollapsed: false,      // Start summaries collapsed (default: false)
  emptyMessage: 'No trends',      // Empty state message
  onTrendClick: (trend, index) => {},  // Click callback
  classNames: {                   // Custom CSS classes
    container: 'trends-ui',
    card: 'trend-card',
    // ... see TypeScript definitions for all options
  }
});

// Load AI summaries (optional)
trends.loadSummaries([
  '#JavaScript - A popular programming language discussion',
  'TypeScript - Microsoft\'s typed JavaScript superset'
]);

// Or load from a map
trends.loadSummariesMap({
  '#javascript': 'A popular programming language discussion',
  'typescript': 'Microsoft\'s typed JavaScript superset'
});

// Render trends
trends.render({
  location: 'United States',
  trends: [
    { name: '#JavaScript', url: '...', rank: 1, tweet_volume: 125000 },
    { name: 'TypeScript', url: '...', rank: 2, tweet_volume: 89000 }
  ]
});

// Get current data
const currentTrends = trends.getTrends();
const location = trends.getLocation();

// Cleanup
trends.clear();   // Clear content
trends.destroy(); // Remove component

FloatingTags

Animated floating tags showing popular trends based on frequency.

const tags = new FloatingTags({
  container: '#floating-tags',
  limit: 20,           // Max tags to show (default: 20)
  hoursWindow: 24,     // Hours of data to consider (default: 24)
  onTagClick: (tag) => console.log(tag.name)
});

// Load from snapshots payload
tags.loadFromSnapshots({
  updated_at: '2024-01-15T12:00:00Z',
  snapshots: [
    {
      timestamp: 1705320000,
      trends: [
        { name: '#JavaScript', url: '...' },
        { name: 'TypeScript', url: '...' }
      ]
    }
  ]
});

// Or render directly with processed data
tags.render([
  { name: '#JavaScript', url: '...', count: 15 },
  { name: 'TypeScript', url: '...', count: 12 }
]);

tags.show();
tags.hide();
tags.destroy();

Timeline

Horizontal scrollable timeline showing historical trend data.

const timeline = new Timeline({
  container: '#timeline',
  initialVisible: 10,  // Trends per column before "Load more" (default: 10)
  emptyMessage: 'No timeline data',
  onTrendClick: (trend, snapshot, index) => {
    console.log(`${trend.name} was trending ${snapshot.hour}h ago`);
  }
});

// Load from payload
timeline.loadFromPayload({
  location: 'Worldwide',
  snapshots: [
    {
      timestamp: 1705320000,
      trends: [
        { name: '#JavaScript', url: '...', rank: 1 }
      ]
    }
  ]
});

// Or render manually
timeline.render([
  {
    hour: 1,
    trends: [
      { name: '#JavaScript', url: '...', rank: 1 }
    ]
  },
  {
    hour: 2,
    trends: [
      { name: 'TypeScript', url: '...', rank: 1 }
    ]
  }
], 'Worldwide');

timeline.setUpdatedLabel(new Date());
timeline.destroy();

Utility Functions

import { formatCount, slugifyLocation, escapeHtml } from 'twitter-trends-ui';

formatCount(125000);        // "125K"
formatCount(1500000);       // "1.5M"
slugifyLocation('United States');  // "united-states"
escapeHtml('<script>');     // "&lt;script&gt;"

Styling

The components use CSS class names that you can style. Here's a minimal example:

.trends-ui {
  font-family: system-ui, sans-serif;
}

.trend-card {
  display: flex;
  align-items: center;
  padding: 12px;
  border-bottom: 1px solid #eee;
}

.trend-rank {
  font-weight: bold;
  width: 30px;
  color: #666;
}

.trend-name {
  color: #1da1f2;
  text-decoration: none;
}

.trend-name:hover {
  text-decoration: underline;
}

.trend-volume {
  font-size: 12px;
  color: #666;
}

.trend-summary {
  margin-top: 8px;
  padding: 8px;
  background: #f5f5f5;
  border-radius: 4px;
}

.trend-summary.collapsed .trend-summary-text {
  display: none;
}

/* Floating tags animation */
.floating-tag {
  display: inline-block;
  padding: 4px 8px;
  margin: 4px;
  border-radius: 4px;
  animation: float var(--float-duration, 5s) ease-in-out infinite;
  animation-delay: var(--float-delay, 0s);
}

@keyframes float {
  0%, 100% { transform: translateY(0); }
  50% { transform: translateY(var(--float-offset, -10px)); }
}

TypeScript

Full TypeScript support is included:

import { TrendsUI, TrendsUIOptions, Trend, TrendsData } from 'twitter-trends-ui';

const options: TrendsUIOptions = {
  container: '#trends',
  showSummaries: true
};

const trends = new TrendsUI(options);

const data: TrendsData = {
  location: 'Worldwide',
  trends: [
    { name: '#TypeScript', url: '...', rank: 1 }
  ]
};

trends.render(data);

Live Demo

See this library in action at TwitterViewer.xyz - a free tool to view Twitter/X trends, profiles, and tweets without needing an account.

Author

TwitterViewer