svg-to-compose

2.2.1indexed

Converts SVG or Android Vector Drawable files into Jetpack Compose Icons, offering command-line and Gradle plugin tools. Features custom parsing for complex vectors and optional optimization.

JSJVMNativeWasm·rafaeltonholo/svg-to-compose

211

Stars

—

Used by

dependents

Health

/ 100

SVG to Compose

A suite of tools to convert SVG or Android Vector Drawable (AVD/XML) files into Android Jetpack Compose Icons. This project provides:

A command-line tool for manual conversion.
A Gradle plugin for automating the conversion within your build process.

Website: svgtocompose.com

For more detailed information on each tool, configurations, and features, please refer to the full documentation:

Why?

With the introduction of Jetpack Compose, Android developers can leverage the full power of Kotlin to build UI components, moving away from traditional XML layouts. However, integrating vector assets like icons often still relies on using Android Vector Drawables (AVD/XML) resources.

This project aims to streamline the integration of vector assets into Compose applications by providing tools that convert SVG or AVD files directly into Compose ImageVector objects, following the same approach used for Google's Material Icons.

Key Advantages:

Custom Parsing Algorithm: The project employs its own parsing algorithm, written on Kotlin Multiplatform, specifically designed to handle complex vector graphics that are not fully supported by the standard library.

Platform Support

Command-line Tool

Platform	Command-line Tool
macOS Arm64

Gradle Plugin

Platform	Gradle Plugin
Android	✅
Kotlin Multiplatform	✅

Available Tools

Command-line Tool

A CLI tool for manually converting SVG or AVD files into Jetpack Compose ImageVector objects. It supports optimization of SVGs and provides various options for customization.

Ideal for CI integration as no additional dependencies are required (not even Java) other than the CLI tool's script and, if you wish, the optimization tools.

Full documentation for the Command-line Tool can be found here.

Gradle Plugin

A Gradle plugin that automates the conversion process within your build system, ideal for projects with a large number of icons or for ensuring consistency and saving development time.

Full documentation for the Gradle Plugin can be found here.

Getting Started

Command-line Tool Installation

Homebrew (macOS / Linux)

brew tap dev-tonholo/svg-to-compose
brew install s2c

Scoop (Windows)

scoop bucket add svg-to-compose https://github.com/dev-tonholo/scoop-svg-to-compose
scoop install s2c

Manual Installation

The CLI tool relies on Kotlin Native to parse the SVG/AVD files. You can install it by:

Downloading the s2c script from this repository and saving it in your preferred folder, or
Cloning the project.

The script will handle downloading or building the native binaries.

After downloading the script or cloning the project:

Give execution permission to the script:
```
chmod +xw s2c
```
Optionally, add the script to your PATH to run it from anywhere:
```
export PATH=<s2c path>:$PATH
```
Replace <s2c path> with the folder's path where you stored the script.

External Dependencies

[!NOTE] This is optional. If you don't want to use external dependencies, make sure to disable optimization via --optimize false when using the CLI tool or by calling the optimize(enabled = false) when using the Gradle Plugin.

[!IMPORTANT] By default, Optimization is enabled by default on both CLI tool and Gradle Plugin.

For SVG optimization, this script relies on:

SVGO: Optimizes SVG files by reducing paths.
```
npm -g install svgo
```
Avocado: Optimizes Android VectorDrawable and AnimatedVectorDrawable XML files.
```
npm -g install avocado
```

Gradle Plugin Installation

The SVG/XML to Compose Gradle Plugin is available on Maven Central. It simplifies the process of converting SVG and Android Vector Drawable (AVG/XML) files into Jetpack Compose ImageVector properties, automating the integration of vector assets into your Compose projects, ensuring a more efficient and error-free workflow.

Applying the plugin

Add the plugin to your module's build.gradle.kts file:

plugins {
    id("dev.tonholo.s2c") version "<latest-version>"
}

Ensure that Maven Central is included in your plugin repositories. If not, add the following to your settings.gradle.kts or build.gradle.kts:

pluginManagement {
    repositories {
        mavenCentral()
        gradlePluginPortal()
    }
}

Configuring .gitignore

Both the CLI tool and the Gradle plugin create a hidden folder to handle the conversion of the vectors without modifying the original file.

To avoid VCS noise, make sure you add the following to your .gitignore which is located in the root folder of your project or the folder you are using the tool in:

.s2c

The algorithm will delete all the contents of the .s2c folder after parsing, but leave it empty. If you delete the folder, it will be recreated on the next run.

Usage

Using the Command-line Tool

[!NOTE] For detailed usage instructions and options, please refer to the Command-line Tool Documentation.

To see all available options, run:

s2c --help

Example Commands

Convert an SVG to a Compose Icon:

s2c -o OutputIconFile.kt \
    -p your.app.package.icon \
    -t your.app.package.theme.YourAppComposeTheme \
    input.svg

Using the Gradle Plugin

[!NOTE] For a complete list of configuration options and advanced usage, please refer to the Gradle Plugin Documentation.

After applying the plugin, configure it in your build.gradle.kts file using the svgToCompose extension. This extension allows you to specify how the SVG/AVG files should be processed and converted.

Basic Configuration Example

svgToCompose {
    processor {
        val projectIcons by creating {
            from(layout.projectDirectory.dir("src/main/resources/icons"))
            destinationPackage("com.example.app.ui.icons")
            icons {
                theme("com.example.app.ui.theme.AppTheme")
            }
            // Additional configurations...
        }
    }
}

Result Examples

Simple SVG File

Without Optimization

Command:

s2c -o <app path>/app/src/main/java/dev/tonholo/composeicons/ui/icon/ShieldSolid.kt \
    -p dev.tonholo.composeicons.ui.icon \
    --theme dev.tonholo.composeicons.ui.theme.ComposeIconsTheme \
    -opt=false \
    <parent-path>/shield-halved-solid.svg

Input file:

Output file: ShieldSolid.nonoptimized.kt

With Optimization

Command:

s2c -o <app path>/app/src/main/java/dev/tonholo/composeicons/ui/icon/ShieldSolid.kt \
    -p dev.tonholo.composeicons.ui.icon \
    --theme dev.tonholo.composeicons.ui.theme.ComposeIconsTheme \
    -opt=true \
    <parent-path>/shield-halved-solid.svg

Input file:

Output file: ShieldSolid.svg.optimized.kt

Complex SVG File

Without Optimization

Command:

s2c -o <app path>/app/src/main/java/dev/tonholo/composeicons/ui/icon/Illustration.kt \
    -p dev.tonholo.composeicons.ui.icon \
    --theme dev.tonholo.composeicons.ui.theme.ComposeIconsTheme \
    -opt=false \
    <parent-path>/illustration.svg

Input file:

Output file: Illustration.svg.nonoptimized.kt

With Optimization

Command:

s2c -o <app path>/app/src/main/java/dev/tonholo/composeicons/ui/icon/Illustration.kt \
    -p dev.tonholo.composeicons.ui.icon \
    --theme dev.tonholo.composeicons.ui.theme.ComposeIconsTheme \
    -opt=true \
    <parent-path>/illustration.svg

Input file:

Output file: Illustration.svg.optimized.kt

Contributing & Community

Contributions are welcome! Please read the CONTRIBUTING.md for setup instructions, coding standards, branching and PR guidelines, and the PR checklist. By participating in this project, you agree to abide by our Code of Conduct.

Have an idea or found a bug? Open an issue: https://github.com/rafaeltonholo/svg-to-compose/issues/new/choose