Skip to main content

​
Icons

Grauity includes a comprehensive icon system with over 450 icons organized into categories. The icon system uses a custom icon font built from the iconland submodule and provides a flexible React component for rendering icons.

​
Installation

Icons are included with the Grauity package. To use icons, you need to import the icon CSS: 
import '@newtonschool/grauity/ui/css/index.scss';
// or if you only need icons
import '@newtonschool/grauity/ui/css/grauity-icons.scss';
The icon fonts are loaded from ui/fonts/grauity-icons.* and include .eot, .ttf, .woff, and .woff2 formats for maximum browser compatibility.

​
NSIcon Component

The NSIcon component (defined in ui/elements/Icon/Icon.tsx:13) is the primary way to render icons in Grauity.

​
Basic Usage

import { NSIcon } from '@newtonschool/grauity';

function MyComponent() {
  return <NSIcon name="sparkle" size="24" />;
}

​
Props

​
name
string
required
The name of the icon to display. See Icon Categories for available icons.
​
size
string
default:"'24'"
The size of the icon in pixels (e.g., "16", "20", "24", "32").
​
color
string
default:"'grey'"
The color of the icon. Accepts any color value or design token.
​
as
React.ElementType
default:"'i'"
The HTML element to render as.
​
className
string
Additional CSS classes to apply.
​
disabled
boolean
default:"false"
Whether the icon is disabled.
​
bordered
boolean
default:"false"
Whether to add a border around the icon.
​
circular
boolean
default:"false"
Whether to render the icon with a circular background.
​
fitted
boolean
default:"false"
Whether to remove extra spacing around the icon.
​
inverted
boolean
default:"false"
Whether to invert the icon colors.
​
link
boolean
default:"false"
Whether the icon should appear as a clickable link.
​
loading
boolean
default:"false"
Whether the icon should display a loading animation.
​
flipped
'horizontal' | 'vertical'
Flip the icon horizontally or vertically.
​
rotated
'90' | '180' | '270'
Rotate the icon by the specified degrees.
​
ariaLabel
string
Accessible label for the icon (for screen readers).
​
ariaHidden
string
default:"'true'"
Whether the icon is hidden from screen readers.
​
onClick
(event: React.MouseEvent) => void
Click handler for the icon.

​
Icon Categories

Grauity’s icons are organized into 14 categories. You can access icon category mappings through the exported constants: 
import { ICON_TAGS, TAG_ICONS } from '@newtonschool/grauity';

// ICON_TAGS: Map icon names to their categories
console.log(ICON_TAGS['sparkle']); // ['Misc']

// TAG_ICONS: Map categories to icon arrays
console.log(TAG_ICONS['System']); // ['arrow-down', 'check', ...]

​
Available Categories

250+ icons for common UI actions and navigation:
  • Arrows: arrow-up, arrow-down, arrow-left, arrow-right
  • Chevrons: chevron-up, chevron-down, chevron-left, chevron-right
  • Actions: check, close, plus, minus, search, filter
  • Controls: menu, gear, refresh, upload, download
  • States: loading, check-circle, close-circle, info-circle
Example icons: check, close, menu, search, gear, arrow-right, chevron-down, home, book, briefcase, bulb, camera, copy, email, globe, link, star
Each icon typically comes in both outlined and filled variants. For example: star and star-filled.

​
Icon Variants

Many icons support different style variants:

​
Filled vs Outlined

import { NSIcon } from '@newtonschool/grauity';

<div>
  <NSIcon name="star" size="24" />
  <NSIcon name="heart" size="24" />
  <NSIcon name="bell" size="24" />
</div>

​
Rotations and Flips

import { NSIcon } from '@newtonschool/grauity';

function IconTransforms() {
  return (
    <div>
      {/* Rotations */}
      <NSIcon name="arrow-up" rotated="90" size="24" />
      <NSIcon name="arrow-up" rotated="180" size="24" />
      <NSIcon name="arrow-up" rotated="270" size="24" />
      
      {/* Flips */}
      <NSIcon name="arrow-right" flipped="horizontal" size="24" />
      <NSIcon name="arrow-down" flipped="vertical" size="24" />
    </div>
  );
}

​
Using Icons in Components

Icons integrate seamlessly with other Grauity components:

​
With Buttons

import { NSButton } from '@newtonschool/grauity';

function MyComponent() {
  return (
    <div>
      <NSButton icon="sparkle" iconPosition="left">
        Get Started
      </NSButton>
      
      <NSButton icon="arrow-right" iconPosition="right" variant="secondary">
        Next
      </NSButton>
      
      <NSButton icon="check" iconPosition="left" color="success">
        Save Changes
      </NSButton>
    </div>
  );
}

​
Standalone Icons

import { NSIcon } from '@newtonschool/grauity';

function StatusIndicator({ status }) {
  const iconMap = {
    success: { name: 'check-circle-filled', color: 'var(--success-500)' },
    error: { name: 'close-circle-filled', color: 'var(--error-500)' },
    warning: { name: 'exclamation-triangle-filled', color: 'var(--warning-500)' },
    info: { name: 'info-circle-filled', color: 'var(--brand-500)' },
  };
  
  const icon = iconMap[status];
  
  return (
    <NSIcon 
      name={icon.name} 
      size="20" 
      color={icon.color}
    />
  );
}

​
Icon Font Build Process

The icon font is built from the iconland Git submodule. Do not edit the generated font files directly.
Grauity’s icon system uses a custom build process:
  1. Source: Icons are stored as SVG files in the iconland submodule
  2. Build: The build process converts SVGs to an icon font
  3. Output: Generated files in ui/fonts/:
    • grauity-icons.eot
    • grauity-icons.ttf
    • grauity-icons.woff
    • grauity-icons.woff2
  4. CSS: The grauity-icons.scss file defines icon classes and mappings

​
Adding New Icons

To add new icons to Grauity:
  1. Add SVG files to the iconland submodule
  2. Update the icon mappings in ui/core/icons/iconTags.ts
  3. Rebuild the icon font
  4. Update the CSS

​
Accessibility

Grauity icons are designed with accessibility in mind: 
// For purely decorative icons
<NSIcon name="sparkle" size="20" ariaHidden="true" />
By default, icons have aria-hidden="true". Always provide an ariaLabel when an icon is used as a standalone interactive element.

​
Best Practices

Consistent Sizing

Use consistent icon sizes throughout your app. Common sizes: 16px, 20px, 24px, 32px.

Filled vs Outlined

Use filled icons for active/selected states, outlined for inactive/default states.

Accessibility

Always provide aria labels for standalone interactive icons.

Loading States

Use the loading prop with the loading icon for async actions.

​
Finding Icons

To explore all available icons, check:
  • Source code: ui/core/icons/iconTags.ts contains the complete icon list
  • Storybook: Browse icons interactively in the Grauity Storybook
  • Constants: Import ICON_TAGS and TAG_ICONS to programmatically access icon lists
import { TAG_ICONS, ICON_TAGS } from '@newtonschool/grauity';

// Get all system icons
const systemIcons = TAG_ICONS['System'];

// Get category for a specific icon
const category = ICON_TAGS['sparkle']; // ['Misc']

​
Related

Build docs developers (and LLMs) love

Get started for freeTalk to us