Add lucide v12 by joyenjoyer · Pull Request #2250 · instructure/instructure-ui

joyenjoyer · 2025-11-18T14:09:59Z

feat(ui-icons-lucide): Add Lucide Icons Package

Overview

This commit introduces a new @instructure/ui-icons-lucide package, providing 1,500+ modern icons from the Lucide icon library with full InstUI theming integration. This replaces the deprecated legacy icon system with a more flexible, maintainable solution built on a pure API.

What's Added

New Package: `ui-icons-lucide`

1,500+ Lucide icons wrapped with InstUI theming support
wrapLucideIcon HOC for custom icon wrapping with InstUI features
Icon mapping (mapping.json) for migrating from legacy InstUI icons to Lucide
TypeScript support with full type definitions

Key Features

Dual API Support
- Semantic InstUI props: size="lg", color="successColor"
- Native Lucide props: size={24}, color="#ff0000"
- Props are composable and override each other intelligently
InstUI Theming Integration
- Full support for InstUI theme tokens (60+ semantic color options)
- Semantic sizing: xs, sm, md, lg, xl, 2xl
- Semantic stroke widths with theme-based values
RTL Support
- Automatic horizontal flipping for bidirectional icons in RTL contexts
- Configurable via bidirectional prop (default: true)
Rotation & Positioning
- Support for 0°, 90°, 180°, 270° rotation
- Inline or block display modes
- Works correctly with RTL transformations
Accessibility
- Support for title and description props
- Automatic role="img" and aria-label when title is provided
- Falls back to aria-hidden="true" for decorative icons

Documentation Gallery Updates

Tabbed interface separating Lucide icons (new) from Legacy icons (deprecated)
Virtualized grid rendering using react-window for optimal performance with 1,500+ icons
Real-time search with debounced filtering
RTL preview toggle to test bidirectional behavior
Modal code examples showing usage for each icon
4-column responsive layout with proper overflow handling

Migration Support

mapping.json provides direct mappings from legacy InstUI icons to Lucide equivalents
Enables automated migration via codemods (to be developed)
Clear deprecation warnings in Legacy Icons gallery

Technical Implementation

Architecture

Wrapper Pattern: Each Lucide icon is wrapped via wrapLucideIcon() HOC
Theme-Aware: Uses useTheme() to access InstUI theme tokens
Style Generation: Emotion-based styles with theme overrides support
Ref Forwarding: InstUI elementRef pattern for DOM access

Build System

generateIndex.ts script auto-generates exports for all 1,500+ icons
TypeScript project references for optimal build performance
Tree-shakeable exports for minimal bundle size

Testing Plan

Manual Testing

1. Icon Gallery Functionality

Navigate to the Icons page in the documentation
Verify both tabs are visible: "Lucide Icons (New)" and "Legacy Icons (Deprecated)"
Switch between tabs and confirm instant switching (galleries remain mounted)

2. Icon Usage Testing

import { Plus, ArrowLeft, Check, X } from '@instructure/ui-icons-lucide'

// Test semantic sizing
<Plus size="xs" />
<Plus size="sm" />
<Plus size="md" />
<Plus size="lg" />
<Plus size="xl" />
<Plus size="2xl" />

// Test numeric sizing
<Plus size={16} />
<Plus size={24} />
<Plus size={32} />

// Test semantic colors
<Check color="successColor" />
<X color="errorColor" />
<Plus color="actionPrimaryBaseColor" />

// Test custom colors
<Plus color="#ff0000" />
<Plus color="rgb(0, 255, 0)" />

// Test rotation
<ArrowLeft rotate="0" />
<ArrowLeft rotate="90" />
<ArrowLeft rotate="180" />
<ArrowLeft rotate="270" />

// Test RTL behavior
<div dir="rtl">
  <ArrowLeft bidirectional={true} /> {/* Should flip */}
  <ArrowLeft bidirectional={false} /> {/* Should not flip */}
</div>

// Test accessibility
<Plus title="Add item" description="Click to add a new item" />

// Test ref access
const iconRef = (el) => console.log(el)
<Plus elementRef={iconRef} />

Breaking Changes

None - this is an additive change. Legacy icons remain functional but deprecated.

This PR description was created with assistance from Claude AI

github-actions · 2025-11-18T14:14:41Z

PR Preview Action v1.6.3
🚀 View preview at https://instructure.design/pr-preview/pr-2250/
Built to branch `gh-pages` at 2025-11-26 10:31 UTC. Preview will be ready when the GitHub Pages deployment is complete.

packages/ui-icons-lucide/src/wrapLucideIcon/index.tsx

packages/ui-icons-lucide/src/wrapLucideIcon/styles.ts

joyenjoyer · 2025-11-23T23:00:12Z

packages/ui-icons-lucide/scripts/generateIndex.ts

+
+const CONFLICTING_NAMES = ['Infinity', 'Map']
+
+function generateIndex() {


If we want to update to a new Lucid version, this function has to be run to generate an updated list of icons in the index.tsx. I will add this info to the documentation (in another PR).

packages/ui-icons-lucide/scripts/generateIndex.ts

joyenjoyer · 2025-11-23T23:03:22Z

packages/ui-icons-lucide/src/mapping.json

@@ -0,0 +1,114 @@
+{


This is an example mapping file between old and new icons. If Alex is ready with the mapping, this is going to be changed for that version.

packages/ui-icons-lucide/src/wrapLucideIcon/index.tsx

matyasf · 2025-11-24T11:07:21Z

packages/__docs__/src/react-window.d.ts

@@ -0,0 +1,49 @@
+/*


This is not needed because if you use the latest version of React-window it supplies its own types.

This is still not needed

matyasf · 2025-11-24T11:07:49Z

packages/__docs__/package.json

    "moment": "^2.30.1",
    "react": "18.3.1",
    "react-dom": "18.3.1",
+    "react-window": "^1.8.10",


Please use the latest version

this is still using an old version

packages/ui-icons-lucide/scripts/generateIndex.ts

matyasf

Nice work, overall I think it looks good :)
Can you also please write a list to the upgrade guide about which props are removed/changed compared to old icons?

matyasf · 2025-11-24T13:21:13Z

packages/ui-icons-lucide/src/wrapLucideIcon/index.tsx

+    const accessibilityProps: Record<string, string | boolean> = {}
+    if (title) {
+      accessibilityProps['aria-label'] = description
+        ? `${title}: ${description}`
+        : title
+      accessibilityProps['role'] = 'img'
+    } else {
+      accessibilityProps['aria-hidden'] = 'true'
+      accessibilityProps['role'] = 'presentation'


As I see in the code the old InlineSVG added a <title> tag when the title prop was specified; description added a <description> that and connected these to the svg with aria-labelledby. Why is this here differently?

We discussed that title stays, description will be removed.

HTML props are spread over to the underlying <svg> -> add this to ugprade guide.

packages/ui-icons-lucide/src/wrapLucideIcon/index.tsx

packages/ui-icons-lucide/package.json

packages/ui-icons-lucide/src/wrapLucideIcon/styles.ts

packages/ui-icons-lucide/src/wrapLucideIcon/props.ts

packages/ui-icons-lucide/src/wrapLucideIcon/index.tsx

matyasf

see my comments

docs/guides/upgrade-guide.md

matyasf · 2025-11-25T15:17:03Z

packages/ui-icons-lucide/src/wrapLucideIcon/styles.ts

  color?: string
-  rotate?: '0' | '90' | '180' | '270'
+  rotate?: LucideIconWrapperProps['rotate']
  bidirectional?: boolean
  inline?: boolean


themse need the same prop ref too, so if we change the prop, this one changes too

matyasf · 2025-11-25T15:18:29Z

packages/__docs__/src/react-window.d.ts

@@ -0,0 +1,49 @@
+/*


This is still not needed

matyasf · 2025-11-25T15:20:34Z

packages/__docs__/package.json

    "moment": "^2.30.1",
    "react": "18.3.1",
    "react-dom": "18.3.1",
+    "react-window": "^1.8.10",


this is still using an old version

joyenjoyer · 2025-11-25T16:41:18Z

packages/__docs__/src/Icons/LegacyIconsGallery.tsx


+// Empty object constant for cellProps to maintain referential equality
+// and prevent unnecessary re-renders of all cells
+const EMPTY_CELL_PROPS = {}


If an empty object without a reference is assigned to cellProps on Grid it keeps rerendering, this trick prevents it.

joyenjoyer · 2025-11-25T16:42:04Z

packages/__docs__/src/Icons/LucideIconsGallery.tsx


+// Empty object constant for cellProps to maintain referential equality
+// and prevent unnecessary re-renders of all cells
+const EMPTY_CELL_PROPS = {}


If an empty object without a reference is assigned to cellProps on Grid it keeps rerendering, this trick prevents it.

matyasf

looks good now

joyenjoyer changed the base branch from master to v12 November 18, 2025 14:10

joyenjoyer commented Nov 18, 2025

View reviewed changes

packages/ui-icons-lucide/src/wrapLucideIcon/index.tsx Outdated Show resolved Hide resolved

joyenjoyer commented Nov 18, 2025

View reviewed changes

packages/ui-icons-lucide/src/wrapLucideIcon/index.tsx Outdated Show resolved Hide resolved

joyenjoyer commented Nov 18, 2025

View reviewed changes

packages/ui-icons-lucide/src/wrapLucideIcon/styles.ts Outdated Show resolved Hide resolved

joyenjoyer commented Nov 18, 2025

View reviewed changes

packages/ui-icons-lucide/src/wrapLucideIcon/styles.ts Outdated Show resolved Hide resolved

joyenjoyer force-pushed the add_lucide_v12 branch 2 times, most recently from 9f618d2 to f083632 Compare November 23, 2025 22:54

joyenjoyer commented Nov 23, 2025

View reviewed changes

packages/ui-icons-lucide/scripts/generateIndex.ts Outdated Show resolved Hide resolved

joyenjoyer commented Nov 23, 2025

View reviewed changes

packages/ui-icons-lucide/src/wrapLucideIcon/index.tsx Outdated Show resolved Hide resolved

joyenjoyer force-pushed the add_lucide_v12 branch from f083632 to 4877ec6 Compare November 23, 2025 23:23

joyenjoyer self-assigned this Nov 23, 2025

joyenjoyer requested review from HerrTopi and matyasf November 23, 2025 23:34

joyenjoyer marked this pull request as ready for review November 23, 2025 23:35

matyasf reviewed Nov 24, 2025

View reviewed changes

matyasf requested changes Nov 24, 2025

View reviewed changes

joyenjoyer force-pushed the add_lucide_v12 branch from f34af3a to affcac0 Compare November 25, 2025 14:12

joyenjoyer requested a review from matyasf November 25, 2025 14:16

matyasf requested changes Nov 25, 2025

View reviewed changes

joyenjoyer force-pushed the add_lucide_v12 branch from affcac0 to b8a0fca Compare November 25, 2025 16:38

joyenjoyer commented Nov 25, 2025

View reviewed changes

joyenjoyer requested a review from matyasf November 25, 2025 16:42

matyasf approved these changes Nov 25, 2025

View reviewed changes

HerrTopi approved these changes Nov 26, 2025

View reviewed changes

feat(ui-icons-lucide): add lucide icons

0913b71

joyenjoyer force-pushed the add_lucide_v12 branch from b8a0fca to 0913b71 Compare November 26, 2025 10:27

joyenjoyer merged commit c1aba7a into v12 Nov 26, 2025
6 checks passed

joyenjoyer deleted the add_lucide_v12 branch November 26, 2025 10:27


		const CONFLICTING_NAMES = ['Infinity', 'Map']

		function generateIndex() {

Conversation

joyenjoyer commented Nov 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

feat(ui-icons-lucide): Add Lucide Icons Package

Overview

What's Added

New Package: ui-icons-lucide

Key Features

Documentation Gallery Updates

Migration Support

Technical Implementation

Architecture

Build System

Testing Plan

Manual Testing

1. Icon Gallery Functionality

2. Icon Usage Testing

Breaking Changes

Uh oh!

github-actions bot commented Nov 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Built to branch gh-pages at 2025-11-26 10:31 UTC. Preview will be ready when the GitHub Pages deployment is complete.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

joyenjoyer Nov 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

matyasf left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

matyasf left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

matyasf left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

joyenjoyer commented Nov 18, 2025 •

edited

Loading

New Package: `ui-icons-lucide`

github-actions bot commented Nov 18, 2025 •

edited

Loading

Built to branch `gh-pages` at 2025-11-26 10:31 UTC.
Preview will be ready when the GitHub Pages deployment is complete.

joyenjoyer Nov 23, 2025 •

edited

Loading