Creating Dynamic SVG Gradients with Next.js

Originally posted at ReCodes26.dev

When creating my portfolio website, I needed placeholder images for my incomplete ideas section. I decided that a nice linear gradient would match my website's theme, so I headed over to Google and searched for free placeholder gradient APIs. To my surprise, I couldn't find a gradient API that satisfied my needs. Some of the APIs were down, some required you to add text inside the gradient, and some offered SVG gradients, but no API. I needed something that was plug-and-play easy, like LoremPicsum, but for gradients, which led me to my latest idea:

PlaceGradient, an open-source, free API that generates placeholder SVG gradients.

What I needed

Most of the gradient generators produced pretty gradients, but they did not provide an API usable in image components. Since manually creating placeholder gradients in Inkscape is time-consuming, I wanted a tiny API to generate random SVG images at runtime.
I needed something that has this:

• Fast SVG gradient generation via API
• No onsite image storage
• URL-based gradient customization
• No setup
• Simple color customization

Ultimately, I needed something fast, easy to use, and that works; that was my inspiration for PlaceGradients. So that's when I grabbed my notebook, wrote down my ideas, and started building.

Development process

I decided to go with NextJS for this project because it offers excellent file-based routing and zero infrastructure setup, which works perfectly with Vecel. Initially, I thought creating a public API would be complicated with backend setup, CORS, security, etc. Still, with NextJS, it was surprisingly simple.

Since this was a small, focused developer tool, I kept the tech stack lightweight:

• NextJS
• Typescript
• Tailwind
• Vercel

For the app, I made a few specific design choices:

SVG Image Generation

I chose to generate an SVG gradient instead of PNG or JPEG files. The main reason for this decision is that SVGs typically have smaller file sizes than other image formats. Plus, unlike traditional image formats, SVGs are infinitely scalable. They will look crisp no matter the size, making it versatile for responsive image components. Since SVGs are essentially code, I created a base SVG string that could be used for all the generated gradients. Additionally, SVGs support native <linearGradient> elements, making them an obvious choice for gradient generation.

Colors

The API was designed to be as straightforward and ready to use as possible. I did not want to have to define all the colors my gradient should use; just give it the base color, and it does the rest. The challenge here is choosing what colors to use for the gradient. Random color selection would result in colors clashing and looking discordant, not what I wanted for my app. My solution was to use color theory to determine which colors look harmonious together, creating a cohesive color scheme. The harmonies I chose were:

• Complementary: Pairs two colors that sit directly opposite each other on the wheel for a high contrast look.

• Analogous: Uses colors that sit right next to each other on the color wheel for a natural look.

• Monochromatic: Uses variations of shades of a single base color for a smooth light-to-dark look.

The generator simply gets the base color, generates a harmonious color scheme, and outputs the results. No other colors or manual input needed.

With PlaceGradients, you can specify a base color to use for your gradient. Instead of making users remember hex values, you can use over 140 CSS color names, such as DarkSlateBlue, Magenta, ForestGreen, etc, as your base color. This design choice was made purely for convenience, to make the gradient creation process easier for developers. Both the color theory and the base color can be customized or omitted, and the API will generate a random gradient.

Seed-based Generation

In certain situations, developers need a deterministic seed-based gradient image. To accommodate this, I added seed-based randomization to my generation system. By specifying a seed, you can produce the exact same gradient each time. Furthermore, anyone with the URL can view that identical gradient.

Challenges

One thing I underestimated was validation. Since every parameter is provided in the URL, I had to validate the color, theory, and seed. This seemed like an easy task, but it took me a few hours of implementation. I used the Zod library to validate the data; however, it had a slight learning curve. I was able to get the validation working with the help of AI. In the future, I wish to truly understand Zod validation myself.

What I would improve

This project taught me a lot about API's, caching, and dynamically generating SVGs. In a future update, I plan to add support for hex color codes in addition to the existing CSS color names. This enhancement will require the validation system to check for both valid CSS colors and valid hex color codes. I would also like to improve the validation system with better error messages and tighter validation. For example, users can type two color parameters. While this will not break the generator, this should not be allowed, as the generator only accepts one color at the moment.

Wrap-up

Creating PlaceGradients was a fun weekend open-source project. I learned that even building small tools can teach a lot about API design, software design, user experience, validation, caching, and deployment. I plan to expand the tool for further customization, tighten validation, improve security, and test edge cases.

PlaceGradients is free and open source. If you would like to try out the API for yourself, you can paste this URL in your browser to get a random gradient:

https://placegradient.recodes26.dev/api

Or you can find PlaceGradients here:

• Github
• Live Website

If you have suggestions or improvements for PlaceGradients, feel free to leave a comment below. You are welcome to contribute to the project on GitHub as well.