Core API

The Core API is the small surface you use to turn gradient strings into gradiente models, validate user input, normalize output, and send gradients to renderers.

It is built around one practical idea: parse once, then reuse the same gradient model everywhere.

Core API Flowlinear-gradient(120deg, #ff74f6 0%, #405de6 55%, #12c2e9 100%)

This preview is rendered from a parsed gradiente model through transformTo('css', gradient).

import { parse, transformTo } from 'gradiente'

const gradient = parse(
  'linear-gradient(120deg, #ff74f6 0%, #405de6 55%, #12c2e9 100%)'
)

const css = transformTo('css', gradient)

The string is still the friendly input and output format. The parsed object is the stable model you can inspect, edit, serialize, compare, and transform.

API Map

parse()        string -> gradient object
isGradient()   unknown string -> boolean
format()       string | gradient object -> normalized string
transformTo()  string | gradient object -> renderer output
transformFrom() target output -> gradient object, when a reverse transformer exists

Most application code starts with parse(), validates with isGradient() when input comes from users, stores normalized strings with format(), and renders through transformTo().

Parse Into A Model

Use parse() when you want to stop treating a gradient as a raw string.

import { parse } from 'gradiente'

const gradient = parse('linear-gradient(to right, red 0%, blue 100%)')

gradient.type
gradient.getConfig()
gradient.toString()

The returned object is a typed gradient instance. For gradients with stops, you can also inspect the stop list.

import { parse } from 'gradiente'

const gradient = parse('linear-gradient(to right, red 0%, blue 100%)')

if ('getStops' in gradient) {
  const stops = gradient.getStops()
}

This is the main difference between gradiente and a string helper. The string is parsed into a reusable model before it is sent to a renderer.

Validate User Input

Use isGradient() when the input may be invalid and you need a safe boolean check.

import { isGradient, parse } from 'gradiente'

const input = 'conic-gradient(from 74deg, #d53f96, #ef9439, #077fe9)'

if (isGradient(input)) {
  const gradient = parse(input)
}

Use parse() when invalid input should throw an error with a concrete reason. Use isGradient() when validation should not interrupt the UI.

Normalize Before Saving

Use format() when you want a canonical string after parsing.

import { format } from 'gradiente'

const normalized = format('linear-gradient(to right, red, blue)')

format() accepts both strings and existing gradient objects.

import { format, parse } from 'gradiente'

const gradient = parse('linear-gradient(red, blue)')
const normalized = format(gradient)

This is useful before saving presets, storing editor state, syncing data, or comparing gradient definitions.

Render With CSS

Use the css target when you need a CSS background value.

import { parse, transformTo } from 'gradiente'

const gradient = parse('linear-gradient(to right, #ff74f6, #405de6)')
const css = transformTo('css', gradient)

const preview = document.querySelector<HTMLElement>('.preview')

if (preview) {
  preview.style.backgroundImage = css
}

Visual result:

HTML/CSS background rendered by transformTo('css', gradient).

For native CSS gradient kinds, the output is a CSS gradient string. For gradiente-specific kinds such as diamond-gradient and mesh-gradient, the CSS transformer returns a renderable adapter background.

import { transformTo } from 'gradiente'

const css = transformTo(
  'css',
  'diamond-gradient(at center, #5851db 0%, #fcb045 100%)'
)

Render With Canvas 2D

Use the canvas-2d target when you want gradiente to draw into a CanvasRenderingContext2D.

import { transformTo } from 'gradiente'

const canvas = document.querySelector<HTMLCanvasElement>('canvas')
const paint = transformTo(
  'canvas-2d',
  'radial-gradient(circle at 30% 35%, #ffffff 0%, #ff74f6 35%, #405de6 100%)'
)

if (canvas) {
  const ctx = canvas.getContext('2d')

  if (ctx) {
    canvas.width = canvas.clientWidth
    canvas.height = canvas.clientHeight
    paint.draw(ctx, canvas.width, canvas.height)
  }
}

Visual result:

Canvas 2D preview rendered by transformTo('canvas-2d', gradient).

The returned object is renderer-specific output. For Canvas 2D, that output is a paint object with a draw(ctx, width, height) method.

Render With WebGL

Use the canvas-webgl target when the gradient should be drawn through WebGL.

import { transformTo } from 'gradiente'

const canvas = document.querySelector<HTMLCanvasElement>('canvas')
const paint = transformTo(
  'canvas-webgl',
  'conic-gradient(from 74deg at 50% 50%, #d53f96, #ef9439 63%, #077fe9)'
)

if (canvas) {
  canvas.width = canvas.clientWidth
  canvas.height = canvas.clientHeight
  paint.draw(canvas, canvas.width, canvas.height)
}

Visual result:

Canvas WebGL preview rendered by transformTo('canvas-webgl', gradient).

The API stays the same: the application asks for a target, and the transformer returns the output shape for that target.

Render With SVG

Use the svg target when you need SVG paint server output.

import { transformTo } from 'gradiente'

const svg = document.querySelector<SVGSVGElement>('svg')
const rect = svg?.querySelector<SVGRectElement>('rect')
const paint = transformTo('svg', 'linear-gradient(to right, #ff74f6, #405de6)')

if (svg && rect) {
  svg.insertAdjacentHTML('afterbegin', paint.defs)
  rect.setAttribute('fill', paint.url)
}

The SVG transformer returns a description that includes defs, url, and the serialized SVG data needed to apply the gradient.

Import From Other Targets

transformFrom() is the reverse side of the transformer system.

import { transformFrom } from 'gradiente'

declare const token: unknown

const gradient = transformFrom(
  'design-token',
  'linear-gradient',
  token
)

Reverse transformation is available when the registered transformer module implements from(). This keeps the Core API symmetric without forcing every renderer output to be reversible.

Working Model

user input
  -> isGradient()
  -> parse()
  -> gradient object
  -> format()
  -> stored normalized string

gradient object
  -> transformTo('css')
  -> transformTo('canvas-2d')
  -> transformTo('canvas-webgl')
  -> transformTo('svg')
  -> transformTo('custom-target')

Next Step

• Transformers explains renderer targets in more detail.
• Custom transformers explains how to add your own targets.