Working with Icons

Overview

Latch uses Lucide React icons throughout the application. This guide explains the pattern for adding and configuring icons in your components and config files.

Icon Pattern: Config files store icon names as strings, then components import specific icons from lucide-react and map them using an iconMap object.

How It Works

1. Config File
2. Component
Bundle Impact

In your config files, icons are defined as PascalCase string names:

config/example.ts

export const exampleConfig = {
  features: [
    {
      title: "Fast Performance",
      icon: "Zap", // String name matching Lucide icon
      color: "blue",
    },
    {
      title: "Secure",
      icon: "Shield",
      color: "green",
    },
  ],
};

Use exact PascalCase names from lucide.dev/icons

Components import specific icons and create an iconMap:

components/Example.tsx

import { Zap, Shield } from "lucide-react";
import { exampleConfig } from "@/config/example";

const iconMap = { Zap, Shield };

export default function Example() {
  return (
    <div>
      {exampleConfig.features.map((feature) => {
        const Icon = iconMap[feature.icon as keyof typeof iconMap];
        return (
          <div key={feature.title}>
            <Icon className="w-6 h-6" />
            <span>{feature.title}</span>
          </div>
        );
      })}
    </div>
  );
}

Never use import * as LucideIcons from "lucide-react". Always import specific icons to keep your bundle size optimized.

Why Direct Imports Matter

Import Method	Bundle Size	Icons Included
Direct import	~2KB	Only what you use
Wildcard import	~300KB	All 1,000+ icons

// Good: Only bundles 3 icons (~2KB)
import { Shield, Zap, Heart } from "lucide-react";

// Bad: Bundles all icons (~300KB)
import * as LucideIcons from "lucide-react";

Tree-shaking works automatically with direct imports - no configuration needed!

Adding New Icons

Find the Icon

Browse lucide.dev/icons to find the icon you need. Note the exact name (e.g., Zap, Shield, Heart).

Add to Config

Add the icon name as a string in your config file:

icon: "Heart", // Exact name from lucide.dev

Import in Component

Import the icon in your component:

import { Zap, Shield, Heart } from "lucide-react";

Add to iconMap

Add it to the iconMap object:

const iconMap = { Zap, Shield, Heart };

Icon Naming Conventions

All icons use PascalCase in both config and imports for consistency:

// Config
icon: "Shield"

// Component
import { Shield } from "lucide-react";
const iconMap = { Shield };

Always use PascalCase: Icon names in config files must match the exact PascalCase names from lucide.dev/icons.

Real-World Examples

Game Features
Partner Benefits
Navbar
Partner Requirements

export const gamesCommonConfig = {
  features: [
    { title: "DDoS Protection", icon: "Shield", color: "blue" },
    { title: "Instant Setup", icon: "Zap", color: "purple" },
    { title: "NVMe Storage", icon: "HardDrive", color: "green" },
    { title: "24/7 Support", icon: "LifeBuoy", color: "yellow" },
  ],
};

import { Shield, Zap, HardDrive, LifeBuoy, Database, Lock, Globe, Gauge } from "lucide-react";
import { gamesCommonConfig } from "@/config/games/common";

const iconMap = { Shield, Zap, HardDrive, LifeBuoy, Database, Lock, Globe, Gauge };

export default function CommonIncludes() {
  return (
    <div>
      {gamesCommonConfig.features.map((feature) => {
        const Icon = iconMap[feature.icon as keyof typeof iconMap];
        return (
          <div key={feature.title}>
            <Icon className="h-4 w-4" />
            <span>{feature.title}</span>
          </div>
        );
      })}
    </div>
  );
}

8 icons imported - Only bundles what’s actually used across the component

export const partnersConfig = {
  benefits: [
    { title: "Priority Support", icon: "Headphones", color: "blue" },
    { title: "Referral Links", icon: "Link", color: "purple" },
    { title: "Exclusive Perks", icon: "Gift", color: "green" },
    { title: "Giveaway Coins", icon: "Coins", color: "yellow" },
  ],
};

import { Headphones, Link, Gift, Coins } from "lucide-react";
import { partnersConfig } from "@/config/pages/partners";

const iconMap = { Headphones, Link, Gift, Coins };

export default function PartnerBenefits() {
  return (
    <div className="grid grid-cols-4 gap-6">
      {partnersConfig.benefits.map((benefit) => {
        const Icon = iconMap[benefit.icon as keyof typeof iconMap];
        return (
          <div key={benefit.title}>
            <Icon className="w-8 h-8" />
            <h3>{benefit.title}</h3>
            <p>{benefit.description}</p>
          </div>
        );
      })}
    </div>
  );
}

Clean mapping - Icon names in config match imports exactly

export const navbarConfig = {
  buttons: [
    { name: "Docs", href: "/knowledgebase", style: "icon", icon: "BookOpen" },
    {
      name: "Login",
      style: "primary",
      dropdown: [
        { name: "Billing Panel", href: "/billing", icon: "CreditCard" },
        { name: "Game Panel", href: "/panel", icon: "Server" },
      ],
    },
  ],
};

import { ChevronDown, BookOpen, CreditCard, Server } from "lucide-react";
import { navbarButtons } from "@/config/branding.exports";

const iconMap = { BookOpen, CreditCard, Server };

export default function Navbar() {
  return (
    <nav>
      {navbarButtons.map((button) => {
        if (button.style === "icon" && button.icon) {
          const Icon = iconMap[button.icon as keyof typeof iconMap];
          return <Icon className="w-5 h-5" />;
        }
        // ... dropdown logic
      })}
    </nav>
  );
}

Import ChevronDown for dropdown indicators even if not in config

export const partnersConfig = {
  requirements: {
    items: [
      { platform: "YouTube", metric: "5,000+", icon: "Youtube", color: "red" },
      { platform: "Twitch", metric: "2,000+", icon: "Twitch", color: "purple" },
      { platform: "Website", metric: "50K+", icon: "Globe", color: "blue" },
      { platform: "Developer", metric: "1,000+", icon: "Code", color: "green" },
      { platform: "Discord", metric: "3,000+", icon: "MessageCircle", color: "indigo" },
      { platform: "Twitter/X", metric: "10K+", icon: "Twitter", color: "sky" },
    ],
  },
};

import { Youtube, Twitch, Globe, Code, MessageCircle, Twitter } from "lucide-react";
import { partnersConfig } from "@/config/pages/partners";

const iconMap = { Youtube, Twitch, Globe, Code, MessageCircle, Twitter };

export default function PartnerRequirements() {
  return (
    <div className="grid grid-cols-3 gap-6">
      {partnersConfig.requirements.items.map((req) => {
        const Icon = iconMap[req.icon as keyof typeof iconMap];
        return (
          <div key={req.platform}>
            <Icon className="w-8 h-8" />
            <div>{req.platform}</div>
            <div>{req.metric}</div>
          </div>
        );
      })}
    </div>
  );
}

6 platform icons - Mix of social and general icons for requirements

Common Patterns

Icon Sizes
Dynamic Colors
Icon Containers
Conditional Rendering

Standard sizes used throughout Latch:

Size	Tailwind Class	Usage
Small	`w-4 h-4`	Navbar, inline text, breadcrumbs
Medium	`w-5 h-5`	Buttons, cards, list items
Large	`w-6 h-6`	Features, benefits, stats
XL	`w-8 h-8`	Hero sections, headers, highlights
2XL	`w-10 h-10`	Large cards, testimonials
3XL	`w-12 h-12`	Icon containers, showcases

// Navbar icon
<Icon className="w-4 h-4" />

// Feature icon
<Icon className="w-6 h-6" />

// Hero icon
<Icon className="w-8 h-8" />

Apply icon colors dynamically using Tailwind and config values:

// From config color string
<Icon className={`w-6 h-6 text-${feature.color}-500`} />

// With opacity
<Icon className={`w-6 h-6 text-${feature.color}-500/70`} />

// Hover states
<Icon className={`w-6 h-6 text-${color}-500 hover:text-${color}-600`} />

Common color values in configs:

blue, purple, green, red, yellow
indigo, sky, pink, orange, teal

Tailwind’s JIT requires complete class names. Dynamic colors work because Latch uses a limited set of predefined colors.

Wrap icons in styled containers for emphasis:

<div className="flex h-12 w-12 items-center justify-center rounded-lg bg-blue-500/10 border border-blue-500/20">
  <Icon className="h-6 w-6 text-blue-500" />
</div>

<div className="flex h-14 w-14 items-center justify-center rounded-xl bg-gradient-to-br from-blue-500/20 to-purple-500/20 border border-white/10">
  <Icon className="h-7 w-7 text-white" />
</div>

<div className="flex h-12 w-12 items-center justify-center rounded-lg bg-blue-500/10 border border-blue-500/20 transition-all hover:scale-110 hover:bg-blue-500/20">
  <Icon className="h-6 w-6 text-blue-500" />
</div>

Handle optional or dynamic icons safely:

// Safe fallback if icon not in map
const Icon = iconMap[item.icon as keyof typeof iconMap];
if (!Icon) return null;

return <Icon className="w-5 h-5" />;

// Optional icon with default
const Icon = iconMap[item.icon as keyof typeof iconMap] || Shield;
return <Icon className="w-5 h-5" />;

// Conditional icon rendering
{item.icon && (
  <div>
    {(() => {
      const Icon = iconMap[item.icon as keyof typeof iconMap];
      return Icon ? <Icon className="w-5 h-5" /> : null;
    })()}
  </div>
)}

Best Practices

Use Direct Imports

Good:

import { Shield, Zap } from "lucide-react";

Bad:

import * as LucideIcons from "lucide-react"; // Bloats bundle

You can use import * as LucideIcons, but it prevents tree-shaking and bundles ALL 1,000+ icons (~300KB extra) even if you only use 5. Direct imports ensure only used icons are bundled.

Keep iconMap One-Liner

Good:

const iconMap = { Shield, Zap, HardDrive };

Bad:

const iconMap = {
  Shield,
  Zap,
  HardDrive,
}; // Unnecessary verbosity

Match Config Icon Names

Ensure config strings match the exact PascalCase Lucide icon names:

// Config
icon: "MessageCircle" // Exact PascalCase match

// Component
import { MessageCircle } from "lucide-react";
const iconMap = { MessageCircle };

Use Type Safety

const Icon = iconMap[feature.icon as keyof typeof iconMap];

This prevents runtime errors if an icon is missing from the map.

Troubleshooting

Icon not displaying?

Check:

Icon name in config uses exact PascalCase from lucide.dev
Icon is imported in component
Icon is added to iconMap with same name
Icon exists on lucide.dev/icons

Example:

// Config: icon: "Mail"
// Component: import { Mail } from "lucide-react";
// iconMap: { Mail }

TypeScript errors?

Use as keyof typeof iconMap for type safety:

const Icon = iconMap[item.icon as keyof typeof iconMap];

Icon names with spaces or dashes?

Lucide icons use PascalCase with no spaces:

Wrong: “message-circle”
Wrong: “message circle”
Correct: “MessageCircle”

Icon not found in Lucide?

Search lucide.dev/icons
Consider similar alternatives
Use a custom SVG if needed (add to /public/icons/)

Where Icons Are Used

Branding

Navbar icons, social links, logo

Home Page

Hero icons, features, stats, benefits

Game Servers

Game features, common includes, specs

Partners

Benefits, requirements, platform icons

Knowledge Base

Article categories, content blocks

Hardware

Processor features, specifications

Quick Reference

Location	Icon Pattern	Example
Config	PascalCase string	`"Shield"`
Import	Named import	`import { Shield } from "lucide-react"`
iconMap	Object shorthand	`const iconMap = { Shield }`
Usage	Dynamic lookup	`iconMap[item.icon as keyof typeof iconMap]`

When adding multiple icons, do it all at once:

Update config with all icon names
Import all icons in one line
Add all to iconMap in one line

Getting Started

Configuration

Products & Hosting

Page Configuration

Deployment

Help & Resources

Overview

How It Works

Why Direct Imports Matter

Adding New Icons

Icon Naming Conventions

Real-World Examples

Common Patterns

Best Practices

Troubleshooting

Where Icons Are Used

Branding

Home Page

Game Servers

Partners

Knowledge Base

Hardware

Quick Reference

​Overview

​How It Works

​Why Direct Imports Matter

​Adding New Icons

​Icon Naming Conventions

​Real-World Examples

​Common Patterns

​Best Practices

​Troubleshooting

​Where Icons Are Used

Branding

Home Page

Game Servers

Partners

Knowledge Base

Hardware

​Quick Reference

Overview

How It Works

Why Direct Imports Matter

Adding New Icons

Icon Naming Conventions

Real-World Examples

Common Patterns

Best Practices

Troubleshooting

Where Icons Are Used

Quick Reference