{"id":40699596,"url":"https://github.com/aprilnea/gpui-symbols","last_synced_at":"2026-01-26T17:01:21.856Z","repository":{"id":333697456,"uuid":"1138342515","full_name":"AprilNEA/gpui-symbols","owner":"AprilNEA","description":"SF Symbols for GPUI – Render Apple's 9000+ icons in Rust desktop apps with type-safe enums and native macOS rendering","archived":false,"fork":false,"pushed_at":"2026-01-21T15:33:27.000Z","size":888,"stargazers_count":4,"open_issues_count":4,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-01-25T01:47:12.838Z","etag":null,"topics":["desktop-app","gpui","icons","macos","rust","sf-symbols","ui-components","zed-editor"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AprilNEA.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE-APACHE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-20T14:53:11.000Z","updated_at":"2026-01-22T08:47:36.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/AprilNEA/gpui-symbols","commit_stats":null,"previous_names":["aprilnea/gpui-symbols"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/AprilNEA/gpui-symbols","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AprilNEA%2Fgpui-symbols","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AprilNEA%2Fgpui-symbols/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AprilNEA%2Fgpui-symbols/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AprilNEA%2Fgpui-symbols/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AprilNEA","download_url":"https://codeload.github.com/AprilNEA/gpui-symbols/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AprilNEA%2Fgpui-symbols/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28755043,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-25T13:59:49.818Z","status":"ssl_error","status_checked_at":"2026-01-25T13:59:33.728Z","response_time":113,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["desktop-app","gpui","icons","macos","rust","sf-symbols","ui-components","zed-editor"],"created_at":"2026-01-21T12:00:42.578Z","updated_at":"2026-01-25T16:00:57.979Z","avatar_url":"https://github.com/AprilNEA.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# gpui-symbols\n\n[![Crates.io](https://img.shields.io/crates/v/gpui-symbols.svg)](https://crates.io/crates/gpui-symbols)\n[![Documentation](https://docs.rs/gpui-symbols/badge.svg)](https://docs.rs/gpui-symbols)\n[![License](https://img.shields.io/crates/l/gpui-symbols.svg)](https://github.com/AprilNEA/gpui-symbols#license)\n[![Downloads](https://img.shields.io/crates/d/gpui-symbols.svg)](https://crates.io/crates/gpui-symbols)\n\nmacOS SF Symbols rendering for Rust / GPUI applications.\n\n## Installation\n\n```toml\n[dependencies]\ngpui-symbols = \"0.6\"\n\n# With GPUI integration\ngpui-symbols = { version = \"0.7\", features = [\"gpui\"] }\n\n# With Icon component (recommended for GPUI apps)\ngpui-symbols = { version = \"0.7\", features = [\"component\"] }\n```\n\n## Usage\n\n### Basic - Raw RGBA Pixels\n\n```rust\nuse gpui_symbols::SfSymbol;\n\nlet (width, height, rgba_data) = SfSymbol::new(\"star.fill\")\n    .size(32.0)\n    .color(0x000000)\n    .render_rgba()\n    .unwrap();\n```\n\n### With GPUI Integration\n\n```rust\nuse gpui_symbols::SfSymbol;\nuse gpui::{img, ImageSource};\n\nlet image = SfSymbol::new(\"heart.fill\")\n    .size(48.0)\n    .color(0xFF0000)\n    .render()\n    .unwrap();\n\n// Use in GPUI element\nimg(ImageSource::Render(image)).size(px(32.))\n```\n\n### Icon Component (Recommended)\n\nThe `Icon` component provides a high-level API similar to GPUI Components:\n\n```rust\nuse gpui_symbols::Icon;\nuse gpui::px;\n\nfn view(window: \u0026mut Window, cx: \u0026mut Context\u003cSelf\u003e) -\u003e impl IntoElement {\n    div()\n        .child(Icon::new(\"star.fill\"))\n        .child(Icon::new(\"heart.fill\").text_color(0xFF0000).size(px(24.)))\n}\n```\n\n#### Using Preset Symbols (Recommended)\n\nWith the `presets` feature, use type-safe SF Symbols enums directly:\n\n```rust\nuse gpui_symbols::{Icon, sfsymbols::SfSymbolV7};\n\n// All 9000+ SF Symbols as compile-time checked enums\nlet icon = Icon::from_name(SfSymbolV7::StarFill);\nlet heart = Icon::from_name(SfSymbolV7::HeartFill).text_color(0xFF0000);\n```\n\n#### Using Unified Symbol Enum (New in 0.6)\n\nUse `SfSymbol` for a single type covering all SF Symbols versions:\n\n```rust\nuse gpui_symbols::{Icon, sfsymbols::SfSymbol};\n\n// Unified enum with version metadata\nlet icon = Icon::from_name(SfSymbol::Gearshape);\n\n// Check minimum version required\nlet (major, minor) = SfSymbol::Gearshape.min_version(); // (2, 0)\n```\n\nThis is useful for cross-platform abstractions:\n\n```rust\nuse gpui_symbols::sfsymbols::SfSymbol;\n\nenum AppIcon { Settings, Search, Plus }\n\nimpl AppIcon {\n    fn sf_symbol(\u0026self) -\u003e SfSymbol {\n        match self {\n            Self::Settings =\u003e SfSymbol::Gearshape,\n            Self::Search =\u003e SfSymbol::Magnifyingglass,\n            Self::Plus =\u003e SfSymbol::Plus,\n        }\n    }\n}\n```\n\n#### Define Custom Icon Enums\n\nAlternatively, use the `define_icons!` macro:\n\n```rust\nuse gpui_symbols::{Icon, define_icons};\n\ndefine_icons! {\n    pub enum AppIcon {\n        Star =\u003e \"star.fill\",\n        Heart =\u003e \"heart.fill\",\n        Settings =\u003e \"gearshape.fill\",\n    }\n}\n\nlet icon = Icon::from_name(AppIcon::Star).text_color(0xFF0000);\n```\n\n### Aspect Ratio Preservation (New in 0.6.1)\n\nSF Symbols are not always square - for example, `gearshape.2` is wider than tall. The `Icon` component automatically preserves the original aspect ratio:\n\n```rust\n// Non-square symbols render correctly\nIcon::new(\"gearshape\").size(px(32.))     // Square gear\nIcon::new(\"gearshape.2\").size(px(32.))   // Wide: two gears side by side\nIcon::new(\"person.3.fill\").size(px(32.)) // Wide: three people\n```\n\nThe `size()` method sets the maximum dimension while maintaining the symbol's natural proportions.\n\n### Advanced Symbol Options\n\nCustomize weight, scale, and rendering mode:\n\n```rust\nuse gpui_symbols::{Icon, SymbolWeight, SymbolScale, RenderingMode};\n\n// Bold weight icon\nIcon::new(\"star.fill\")\n    .weight(SymbolWeight::Bold)\n    .size(px(24.));\n\n// Large scale with multicolor rendering\nIcon::new(\"cloud.sun.fill\")\n    .symbol_scale(SymbolScale::Large)\n    .rendering_mode(RenderingMode::Multicolor);\n\n// Thin weight, monochrome style\nIcon::new(\"heart.fill\")\n    .weight(SymbolWeight::Thin)\n    .rendering_mode(RenderingMode::Monochrome)\n    .text_color(0xFF0000);\n```\n\n### Integration with gpui-component\n\nUse SF Symbols with [gpui-component](https://github.com/longbridge/gpui-component) Button via `child()`:\n\n```rust\nuse gpui_symbols::{Icon as SfIcon, sfsymbols::SfSymbolV7};\nuse gpui_component::Button;\n\n// Icon-only button\nButton::new(\"star-btn\")\n    .child(SfIcon::from_name(SfSymbolV7::StarFill).size(px(16.)))\n\n// Icon + label button\nButton::new(\"favorite-btn\")\n    .child(\n        div().flex().items_center().gap_2()\n            .child(SfIcon::from_name(SfSymbolV7::HeartFill).size(px(16.)).text_color(0xFF0000))\n            .child(\"Favorite\")\n    )\n```\n\n\u003e **Note**: gpui-component's `Button::icon()` expects SVG paths, while gpui-symbols renders to pixel images. Use `Button::child()` for SF Symbols integration.\n\n## API\n\n### `SfSymbol`\n\nLow-level builder for rendering SF Symbols.\n\n| Method | Description | Default |\n|--------|-------------|---------|\n| `new(name)` | Create symbol with name | - |\n| `size(f32)` | Point size | 32.0 |\n| `scale(f32)` | Scale factor (Retina) | 2.0 |\n| `color(u32)` | RGB hex color | 0x000000 |\n| `weight(SymbolWeight)` | Symbol weight | Regular |\n| `symbol_scale(SymbolScale)` | Symbol scale | Medium |\n| `rendering_mode(RenderingMode)` | Rendering mode | Hierarchical |\n| `render_rgba()` | Render to `(width, height, Vec\u003cu8\u003e)` | - |\n| `render()` | Render to `Arc\u003cRenderImage\u003e` (requires `gpui` feature) | - |\n\n### `Icon`\n\nHigh-level GPUI component (requires `component` feature).\n\n| Method | Description | Default |\n|--------|-------------|---------|\n| `new(name)` | Create icon with SF Symbol name | - |\n| `from_name(T)` | Create from `IconName` type | - |\n| `size(Pixels)` | Set maximum dimension (preserves aspect ratio) | 16px |\n| `color(impl Into\u003cHsla\u003e)` | Set color (Hsla, Rgba, or `rgb(hex)`) | black |\n| `text_color(u32)` | Set RGB hex color (convenience) | black |\n| `weight(SymbolWeight)` | Symbol weight | Regular |\n| `symbol_scale(SymbolScale)` | Symbol scale | Medium |\n| `rendering_mode(RenderingMode)` | Rendering mode | Hierarchical |\n\n### Enums\n\n**`SymbolWeight`**: `UltraLight`, `Thin`, `Light`, `Regular`, `Medium`, `Semibold`, `Bold`, `Heavy`, `Black`\n\n**`SymbolScale`**: `Small`, `Medium`, `Large`\n\n**`RenderingMode`**: `Monochrome`, `Hierarchical`, `Palette`, `Multicolor`\n\n### Cache Management\n\nWith the `cache` feature (enabled by default), rendered symbols are cached globally for performance:\n\n```rust\nuse gpui_symbols::{cache_size, clear_cache};\n\n// Get number of cached symbols\nlet count = cache_size();\n\n// Clear all cached symbols (e.g., on memory pressure or appearance change)\nclear_cache();\n```\n\n## Features\n\n| Feature | Description |\n|---------|-------------|\n| `default` | `component` + `presets` + `cache` |\n| `cache` | Global cache for rendered symbols (implies `gpui`) |\n| `gpui` | GPUI integration, returns `Arc\u003cRenderImage\u003e` |\n| `component` | High-level `Icon` component (implies `gpui`) |\n| `presets` | Type-safe SF Symbols enums via `sfsymbols` crate |\n\n## Requirements\n\n- macOS 11.0+ (SF Symbols support)\n- Rust 1.75+\n\n## Examples\n\nRun the example:\n\n```bash\ncargo run --example basic --features component\n```\n\n## Symbol Names\n\nSee [SF Symbols](https://developer.apple.com/sf-symbols/) for available symbol names.\n\nCommon symbols:\n- `star.fill`, `heart.fill`, `house.fill`\n- `gearshape`, `magnifyingglass`, `trash`\n- `person.fill`, `folder.fill`, `doc.fill`\n\n## Related Crates\n\n| Crate | Description |\n|-------|-------------|\n| [sfsymbols](./sfsymbols) | Type-safe SF Symbols enums (9000+ symbols) |\n| [sfsymbols-codegen](./sfsymbols-codegen) | Code generator for sfsymbols |\n\n## License\n\nMIT OR Apache-2.0\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faprilnea%2Fgpui-symbols","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faprilnea%2Fgpui-symbols","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faprilnea%2Fgpui-symbols/lists"}