!SF Symbols

SF Symbols Library

A React component library providing 7,007 SF Symbols as type-safe React components. Supports multiple rendering variants (hierarchical, monochrome) with optimized bundle sizes through subpath imports.

Features

- 7,007 Symbols - Complete SF Symbols collection
- Type-Safe - Full TypeScript support with autocomplete
- Tree-Shakeable - Import only what you need
- Multiple Variants - Hierarchical, Monochrome
- Optimized Bundles - Separate builds per variant

Live Demo

Explore all available SF Symbols in an interactive grid layout with support for light and dark modes. See the live demo to browse the icons and their usage.

Installation

``bash
npm install sf-symbols-lib
`

Quick Start

`tsx
import { SFSymbol, SFCheckmark } from 'sf-symbols-lib/hierarchical';

function App() {
return ;
}
`

Usage

$3

`tsx
import { SFSymbol, SFCheckmark, SFCheckmarkCircleFill, SFTrash } from 'sf-symbols-lib/hierarchical';

function MyComponent() {
return (


`tsx
// Hierarchical (depth through layering)
import { SFSymbol, Folder } from 'sf-symbols-lib/hierarchical';

// Monochrome (single color, clean)
import { SFSymbol, Folder } from 'sf-symbols-lib/monochrome';
`

$3

If you don't specify a subpath, you get hierarchical:

`tsx
// These are equivalent:
import { SFSymbol, SFCheckmark } from 'sf-symbols-lib';
import { SFSymbol, SFCheckmark } from 'sf-symbols-lib/hierarchical';
`

$3

`tsx
import { SFSymbol, Heart, HeartFill, Star } from 'sf-symbols-lib/hierarchical';

function StyledSymbols() {
return (


Available size presets: xs, sm, md, lg, xl

`tsx
import { SFSymbol, Bell } from 'sf-symbols-lib/hierarchical';

function SizeExamples() {
return (


`tsx
import { SFSymbol, Plus, Trash, PencilLine } from 'sf-symbols-lib/hierarchical';

function ButtonExamples() {
return (


`tsx
import { SFSymbol, SFCheckmarkCircleFill, SFCircle, SFExclamationmarkTriangleFill } from 'sf-symbols-lib/hierarchical';

type Status = 'done' | 'pending' | 'warning';

function StatusList({ items }: { items: { text: string; status: Status }[] }) {
const statusIcons = {
done: { symbol: SFCheckmarkCircleFill, className: 'text-green-500' },
pending: { symbol: SFCircle, className: 'text-gray-400' },
warning: { symbol: SFExclamationmarkTriangleFill, className: 'text-yellow-500' },
};

return (


{items.map((item, i) => {
const icon = statusIcons[item.status];
return (

• 
  
  {item.text}
  

);
})}

`tsx
import { SFSymbol, SFSymbolName, Folder, FolderFill } from 'sf-symbols-lib/hierarchical';

function DynamicIcon({ isOpen }: { isOpen: boolean }) {
return (
name={isOpen ? FolderFill : Folder}
size={24}
/>
);
}
`

$3

For cases where you need to work with symbol names programmatically:

`tsx
import { SFSymbol, SFSymbolName, getAvailableSymbols, isAvailableSymbol } from 'sf-symbols-lib/hierarchical';

// Using enum


// Check if a symbol exists
if (isAvailableSymbol('checkmark.circle.fill')) {
// Symbol exists
}

// Get all available symbols
const allSymbols = getAvailableSymbols();
console.log(Total symbols: ${allSymbols.length}); // 7007
`

Project Configuration

$3

For shorter imports throughout your project, configure a path alias:

tsconfig.json:
`json
{
"compilerOptions": {
"paths": {
"sf-symbols": ["node_modules/sf-symbols-lib/dist/hierarchical"]
}
}
}
`

vite.config.ts (if using Vite):
`ts
export default defineConfig({
resolve: {
alias: {
'sf-symbols': 'sf-symbols-lib/hierarchical'
}
}
});
`

Then use it:
`tsx
import { SFSymbol, SFCheckmark } from 'sf-symbols';
`

$3

Create a local re-export file:

src/lib/sf-symbols.ts:
`tsx
export * from 'sf-symbols-lib/hierarchical';
`

Usage:
`tsx
import { SFSymbol, SFCheckmark } from '@/lib/sf-symbols';
`

This approach makes it easy to switch variants later by changing just one file.

Props Reference

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| name | string | required | Symbol name constant |
| size | number \| string | 24 | Size in pixels or preset (xs, sm, md, lg, xl) |
| className | string | '' | CSS class names |
| strokeWidth | number \| string | 1 | SVG stroke width |
| style | CSSProperties | - | Inline styles |
| ...rest | SVGAttributes | - | Any valid SVG attribute |

Symbol Naming

Symbols are named using PascalCase derived from their SF Symbol names:

| SF Symbol Name | Constant |
|----------------|----------|
| checkmark | SFCheckmark |
| checkmark.circle | SFCheckmarkCircle |
| checkmark.circle.fill | SFCheckmarkCircleFill |
| square.and.arrow.up | SFSquareAndArrowUp |
| 0.circle.fill | SFN0CircleFill |
| 42.square | SFN42Square |

Note: All constants are prefixed with SF. Symbols starting with numbers are additionally prefixed with N.

Bundle Size

Each variant is a separate bundle:

| Import Path | Size (gzip) |
|-------------|-------------|
| sf-symbols-lib/hierarchical | ~3.1 MB |
| sf-symbols-lib/monochrome | ~3.1 MB |

Import only the variant you need to minimize bundle size.

Development

$3

- Node.js >= 22.0.0
- npm

$3

`bash


Install dependencies

1. Add SVG files to the appropriate directory:
`
src/components/svgs/{variant}/{color}/*.svg
`

Example structure:
`
src/components/svgs/
├── hierarchical/
│ └── your-symbol.svg
├── monochrome/
│ └── your-symbol.svg
`

2. Run the generator:
`bash
npm run generate
`

3. Build the library:
`bash
npm run build
`

$3

The generator creates:

- src/components/sf-symbol-name.ts - Enum and constants for all symbol names
- src/{variant}/data.ts - SVG content for each variant
- src/{variant}/index.tsx - Entry point with SFSymbol component
- src/index.ts` - Main entry (re-exports hierarchical)

Contributing

Bug reports and pull requests are welcome. Please use the GitHub issue tracker for bug reports or feature requests.

Disclaimer

This is an unofficial library and is not affiliated with or endorsed by Apple Inc. All SF Symbols included in this library are copyrighted by Apple and are provided solely for reference and learning purposes.

The symbols were manually exported from Apple's SF Symbols app using the built-in export functionality and then processed programmatically to create this React component library. The SVG designs from Apple SF Symbols are compiled into React components and cannot be modified separately.

This library is a React wrapper around Apple's SF Symbols and does not modify or redistribute the original symbol designs in any way that violates Apple's terms.

For official SF Symbols documentation and guidelines, visit Apple's SF Symbols website.

Credits

- SF Symbols are designed and maintained by Apple Inc.
- This React component library was created to provide a convenient way to use SF Symbols in React applications.
- Special thanks to the open-source community for feedback and contributions.

License

This repository has been published under the CC-BY-NC-SA 4.0 license.

---