Awesome AI Tier List Maker

A modern, feature-rich tier list maker with AI-powered suggestions, natural language commands, and OCR image text extraction.
Explore the features »

View Demo · Report Bug · Request Feature

Table of Contents

1. About The Project
   • Built With
2. Features
   • Core Features
   • AI-Powered Features
   • Customization
   • Save & Export
3. Screenshots
4. Getting Started
   • Prerequisites
   • Installation
   • Environment Variables
5. Usage
   • Creating a Tier List
   • Using AI Features
   • Natural Language Commands
6. AI Models
   • Default Models (Low-Cost)
   • Free Model Fallbacks
   • Vision Models for OCR
   • Cost Control
   • Using Different Models
7. Deployment
8. Contributing
9. License
10. Contact
11. Acknowledgments

---

About The Project

The Awesome AI Tier List Maker is a modern web application that allows you to create, customize, and share tier lists with ease. Unlike traditional tier list makers, this application leverages AI to help you:

• Generate item suggestions based on any topic
• Get intelligent tier placement recommendations
• Extract text from images using OCR
• Control the app with natural language commands
• Set up entire tier lists with AI-assisted wizards

Whether you're ranking your favorite movies, video game characters, or anything else, this tool makes the process faster and more intuitive.

(back to top)

Built With

This project is built with modern web technologies:

Technology	Purpose
	UI Framework
	Type Safety
	Build Tool
dnd-kit	Drag and Drop
OpenRouter	AI API Gateway
html-to-image	Export to PNG

(back to top)

---

Features

Core Features

Feature	Description
Drag & Drop	Intuitive drag and drop interface to move items between tiers
Custom Items	Add text items or upload images to your tier list
Inline Editing	Double-click any item to edit its label directly
Image Upload	Upload multiple images at once (up to 20)
OCR Text Extraction	Automatically extract text from uploaded images using AI
Distribution View	See percentage distribution of items across tiers

AI-Powered Features

All AI features are powered by OpenRouter, using low-cost models (~$0.001 per request) with free fallbacks.

Feature	Description
✨ Smart Suggestions	Generate item suggestions based on your tier list topic
✨ AI Tier Placement	Get AI recommendations for where to place items
✨ Description Generator	Generate descriptions explaining your tier list
✨ Setup Wizard	Create entire tier lists from scratch with AI assistance
✨ Natural Commands	Control the app using natural language (e.g., "move Mario to S tier")
✨ OCR Extraction	Extract text from images to create items automatically

Customization

Feature	Description
Custom Tiers	Add, remove, rename, and reorder tiers
Tier Colors	Choose custom colors for each tier
Dark/Light Mode	Toggle between dark and light themes
Title Editing	Customize your tier list title

Save & Export

Feature	Description
Save to Browser	Save tier lists to local storage
Load Saved Lists	Load previously saved tier lists
Export as PNG	Export your tier list as a high-quality image
Reset Tiers	Reset to default S/A/B/C/D configuration

(back to top)

---

Screenshots

Click to view screenshots

Main Interface

The main tier list interface with drag and drop functionality

AI Smart Suggestions

AI-generated item suggestions based on your topic

AI Setup Wizard

Create entire tier lists with AI assistance

Natural Language Commands

Control the app with natural language

Image Upload with OCR

Extract text from uploaded images automatically

Dark Mode

Full dark mode support

Distribution View

See percentage distribution of items across tiers

(back to top)

---

Getting Started

Follow these steps to set up the project locally.

Prerequisites

• Node.js (v18 or higher)
• npm or yarn
• OpenRouter API Key (free) - Get one here

Installation

1. Clone the repository

   git clone https://github.com/aimhco/awesome-ai-tier-list-maker.git
   cd awesome-ai-tier-list-maker/app

2. Install dependencies

   npm install

3. Set up environment variables

   cp .env.example .env.local

4. Add your OpenRouter API key

   Edit .env.local and add your API key:

   VITE_OPENROUTER_API_KEY=your_openrouter_api_key_here

5. Start the development server

   npm run dev

6. Open in browser

   Navigate to http://localhost:5173

Environment Variables

Variable	Description	Default
VITE_OPENROUTER_API_KEY	Your OpenRouter API key (required)	-
VITE_AI_MODE	user for local dev, public for production	user
VITE_AI_MODEL	Comma-separated list of models (with fallbacks)	deepseek/deepseek-v3.2

(back to top)

---

Usage

Creating a Tier List

1. Set a title - Click the title at the top to edit it
2. Add items - Use the "Add Item" button or upload images
3. Drag and drop - Move items between tiers
4. Customize tiers - Click the tier label to edit, or use the settings menu

Using AI Features

Click the AI button (sparkle icon) in the toolbar to access:

Feature	How to Use
Smart Suggestions	Enter a topic and get AI-generated item suggestions
Tier Placement	Select items and get AI recommendations for placement
Description Generator	Generate a description explaining your rankings
Setup Wizard	Enter a topic and let AI create the entire tier list
Natural Commands	Type commands in plain English

Natural Language Commands

The Natural Commands feature understands commands like:

Command	Action
"Move Mario to S tier"	Moves an item to a specific tier
"Create a new tier called Legendary"	Creates a new tier
"Rename tier B to Good"	Renames an existing tier
"Clear all items from D tier"	Removes all items from a tier
"Delete the F tier"	Removes a tier
"Swap S and A tiers"	Swaps the positions of two tiers

Note: Natural Commands works best with one command at a time.

(back to top)

---

AI Models

This application uses OpenRouter as an AI gateway, which provides access to multiple AI models from different providers.

Default Models (Low-Cost)

The app uses low-cost paid models by default for reliability:

Model	Provider	Cost (per 1M tokens)	Purpose
deepseek/deepseek-v3.2	DeepSeek	$0.25 in / $0.38 out	Primary text model
google/gemini-3-flash-preview	Google	$0.50 in / $3.00 out	Vision/OCR model

Why paid models? Free models on OpenRouter are unreliable - they frequently become unavailable without notice. With DeepSeek's pricing, $10 covers ~10,000+ tier list sessions.

Free Model Fallbacks

The app automatically falls back to free models if paid models fail:

Model	Provider	Context	Vision
xiaomi/mimo-v2-flash:free	Xiaomi	262K	No
mistralai/devstral-2512:free	Mistral	262K	No
nvidia/nemotron-nano-12b-v2-vl:free	Nvidia	128K	Yes
allenai/molmo-2-8b:free	AllenAI	36K	Yes

Note: Free models may be discontinued at any time. See OpenRouter's free tier policy.

Vision Models for OCR

For image text extraction (OCR), the app uses vision-capable models:

Model	Provider	Cost
google/gemini-3-flash-preview	Google	$0.50-3.00/M
nvidia/nemotron-nano-12b-v2-vl:free	Nvidia	Free
allenai/molmo-2-8b:free	AllenAI	Free

Cost Control

OpenRouter uses a prepaid credit system - no automatic billing:

• Add credits manually at OpenRouter Credits
• When credits run out, API calls fail (no surprise charges)
• $10 covers thousands of tier list sessions

Using Different Models

You can customize which models to use in your .env.local file:

# Use specific models (comma-separated for fallback order)
VITE_AI_MODEL=deepseek/deepseek-v3.2,xiaomi/mimo-v2-flash:free

# Or use premium models for best quality
VITE_AI_MODEL=openai/gpt-4o,anthropic/claude-sonnet-4

Popular model options:

Model	Provider	Cost	Best For
deepseek/deepseek-v3.2	DeepSeek	$0.25-0.38/M	Best value
google/gemini-3-flash-preview	Google	$0.50-3.00/M	Vision + speed
openai/gpt-4o-mini	OpenAI	$0.15-0.60/M	Good balance
openai/gpt-4o	OpenAI	$2.50-10.00/M	Best quality
anthropic/claude-sonnet-4	Anthropic	$3.00-15.00/M	Complex reasoning

Check current pricing at OpenRouter Models.

(back to top)

---

Deployment

Build for Production

npm run build

The built files will be in the dist directory, ready for deployment to any static hosting service.

Deploy to Vercel

1. Connect your GitHub repository to Vercel
2. Set environment variables in Vercel dashboard:
   • VITE_OPENROUTER_API_KEY = your API key
   • VITE_AI_MODE = public
3. Deploy - Vercel will automatically build and deploy

(back to top)

---

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement".

Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

Top Contributors

(back to top)

---

License

Distributed under the MIT License. See LICENSE for more information.

(back to top)

---

Contact

Denny - denny@aimh.co

Website: https://www.aimh.co

Project Link: https://github.com/aimhco/awesome-ai-tier-list-maker

(back to top)

---

Acknowledgments

Resources and tools that made this project possible:

• OpenRouter - AI API Gateway
• React - UI Framework
• Vite - Build Tool
• dnd-kit - Drag and Drop
• html-to-image - Image Export
• Shields.io - README Badges
• Best-README-Template - README Template

(back to top)

---