Valkyrie

<h2 align="center">Valkyrie — SVG/XML to Compose ImageVector converter</h2> <div align="center"> <img alt="Icon" src="tools/idea-plugin/src/main/resources/META-INF/pluginIcon.svg" width="150" /> </div> <div align="center">

[![Marketplace version][badge:marketplace-version]][url:plugin-homepage] [![Github plugin release][badge:idea-release]][url:gh-releases] [![Downloads][badge:marketplace-downloads]][url:plugin-homepage] [![Rating][badge:marketplace-rating]][url:plugin-homepage]

[![CLI release][badge:cli-release]][url:gh-releases] [![Homebrew][badge:homebrew]][url:homebrew]

[![Gradle Plugin Portal][badge:gradle-plugin]][url:gradle-plugin]

[![Telegram][badge:telegram-invite]][url:telegram-invite] [![Slack][badge:slack-invite]][url:slack-invite] ![Test coverage][badge:coverage] [![License][badge:license]][url:gh-license]

</div>

Motivation

During the development Jetpack Compose / Compose Multiplatform, we often faced the challenge of converting icons from SVG or XML format to ImageVector. While there are existing tools available for this purpose, we found that they often fell short in terms of usability, reliability, and the quality of the generated code and in some cases, even being paid 😄.

To address these issues, we decided to create our own tool that would streamline the conversion process and provide a better user experience.

The primary goal of this project is to offer a fast, reliable, and user-friendly solution for converting SVG and XML icons to ImageVector format, while also allowing for customization of the generated code to meet individual project needs.

[!NOTE] This project is especially relevant now as Material Icons is no longer maintained and not recommended for use in your apps. Learn more.

Available tools:

• 🔌 IntelliJ IDEA / Android Studio plugin
• 🖥️ CLI tool
• 🐘 Gradle plugin
• Web app (🚧 under development 🚧)

Table of Contents

• Key features
• 🔌 IDEA plugin
  • Plugin features
  • Simple mode
  • IconPack mode
    • Create new icon pack
    • Update existing icon pack
  • ImageVector previewer
    • Embedded previewer
    • AutoCompletion previewer
    • Gutter previewer
  • Requirements
  • Installation
  • Build plugin
• 🖥️ CLI tool
  • Install
  • Available commands
    • iconpack command
    • svgxml2imagevector command
    • changelog command
  • Build
• 🐘 Gradle plugin
  • Plugin configuration
  • Samples
    • Basic conversion
    • Icon pack configuration
    • Icon pack with nested packs configuration
  • Tips and tricks
• Other
  • Output formats
  • Comparison with other solutions
  • Migration guide

Key features

Core functionality:

• Support conversion from SVG and XML
• Custom kotlinpoet generator with streamlined code formatting:
  • code alignment and formatting
  • remove redundant code by default (e.g. public keyword)
  • remove unused imports (e.g. kotlin.* package)
  • skip default ImageVector parameters
  • support generation as backing property or lazy property
  • optional trailing comma and explicit mode
  • customize code indent
• Ability to create your unique project icon pack (+nested packs if necessary)
• High performance (6k icons processing ~5sec)

🔌IDEA Plugin

Plugin features

• Two conversion modes: Simple and IconPack
• Support for Drag&Drop files/directories and pasting content from clipboard
• Easy option to add more icons into existing project icon pack
• Copy generated ImageVector to clipboard or file (depends on the mode)
• Fully customizable setting for generated icons
• Build-in ImageVector previewer for any icons without compilation ✨
• The plugin is completely built using Compose Multiplatform and Tiamat navigation library

More exclusive features under development, stay tuned 🌚

Simple mode

[!NOTE] One-click solution to convert SVG/XML to ImageVector (requires only specifying the package).

Available quick actions:

• Rename icon
• Preview current ImageVector
• Copy generated ImageVector to clipboard

<div align="center"> <img src="assets/simple_mode_1.png" width="252" /> <img src="assets/simple_mode_2.png" width="251.2" /> <img src="assets/simple_mode_3.png" width="250" /> </div>

Demo:

https://github.com/user-attachments/assets/f48eb027-ccb2-4194-87bb-868c6be222ae

IconPack mode

New icon pack

[!NOTE] Facilitates creating an organized icon pack with extension properties for your pack object, previewing the list of icons, and batch importing them to your specified directory.

<div align="center"> <img src="assets/iconpack_mode_new_1.png" width="300" /> <img src="assets/iconpack_mode_new_2.png" width="300" /> </div>

Demo:

https://github.com/user-attachments/assets/ccb568a4-bda9-4f2b-bf40-29b1a8e4c854

Existing icon pack

[!NOTE] Instead of importing icon pack settings, the plugin provides a direct way to import an already created icon pack from a Kotlin file.

<div align="center"> <img src="assets/iconpack_mode_existing_1.png" width="300" /> <img src="assets/iconpack_mode_existing_2.png" width="300" /> </div>

[!IMPORTANT] Editing features are limited for now; you can only load an existing pack and add more nested packs.

Demo:

https://github.com/user-attachments/assets/77f449dd-a6d0-44ea-9059-b7b30ee94426

ImageVector Previewer

Embedded Previewer

We personally find it very useful to have a previewer for ImageVector (such we have for SVG or XML). Previewer available for any ImageVector formats (backing or lazy property, legacy google material icons) without compose @Preview annotation and project compilation.

<div align="center"> <img src="assets/imagevector_previewer.png" /> </div>

Previewer actions:

• Change icon background (pixel grid, white, black)
• Zoom in, zoom out icon without loosing quality
• Draw as actual size
• Fit icon to window

Demo:

https://github.com/user-attachments/assets/1047a2b3-81ec-4e10-a118-0ff20bd5227b

AutoCompletion Previewer

When IDEA auto-completion popup is shown for any ImageVector property, the preview image will be displayed in the popup.

<div align="center"> <img src="assets/imagevector_previewer_autocomplete.png" /> </div>

Gutter Previewer

Preview inside gutter available for any ImageVector property. By clicking on the gutter icon, the original file will be opened in the editor with embedded previewer.

<div align="center"> <img src="assets/imagevector_previewer_gutter.png" /> </div>

Requirements

| Plugin version | Min IntelliJ IDEA / Android Studio | |----------------|----------------------------------------------| | 0.1.0 - 0.14.0 | IntelliJ IDEA 2024.1, Android Studio Koala | | 0.15.0 | IntelliJ IDEA 2024.2, Android Studio Ladybug | | 1.0.0 | IntelliJ IDEA 2025.3, Android Studio Panda 1 |

Installation

<a href="https://plugins.jetbrains.com/plugin/24786-valkyrie" target="_blank"> <img src="assets/installation_button.svg" height="40" alt="Get from Marketplace" title="Get from Marketplace"> </a>

• Find plugin inside IDE:

  <kbd>Settings</kbd> > <kbd>Plugins</kbd> > <kbd>Marketplace</kbd> > <kbd>Search for <b>"Valkyrie"</b></kbd> > <kbd>Install Plugin</kbd>

• Manually: Download the latest release or build your self and install it manually using <kbd>Settings</kbd> -> <kbd>Plugins</kbd> -> <kbd>⚙️</kbd> -> <kbd>Install plugin from disk...</kbd>

Build plugin

Precondition: IntelliJ IDEA with installed Plugin DevKit

Run ./gradlew buildPlugin to build plugin locally. Artifact will be available in tools/idea-plugin/build/distributions/ folder

or run plugin in IDE using: ./gradlew runIde

🖥CLI tool

CLI tools can be easily integrated into scripts and automated workflows, allowing you to convert icons from specific source with predefined settings.

Install CLI

• via brew

brew install ComposeGears/repo/valkyrie

• manually via binary release

Download latest CLI tool from releases.

Unzip the downloaded archive and run the CLI tool from bin folder in the terminal

./valkyrie

You should see this message

<div align="center"> <img src="assets/cli_valkyrie.png" width="550" /> </div>

• automatically using bash script

A simple example of how to get the latest version of the CLI tool. It can be executed on CI/CD with predefined parameters.

#!/bin/bash

VERSION="cli-1.0.0"
TARGET_DIR="valkyrie-cli"
ASSET_NAME="tmp.zip"

LATEST_CLI_RELEASE_URL=$(curl --silent "https://api.github.com/repos/ComposeGears/Valkyrie/releases/tags/$VERSION" \
  | jq -r '.assets[] | select(.name | startswith("valkyrie-cli")) | .