@scaleflex/react-url-builder

A React component for visually editing Cloudimage / Filerobot image transformation URL parameters. Drop it into a page, point it at an image URL, and users can adjust format, size, position, filters, watermarks, and AI tools through a tabbed UI while the generated URL updates live.

Install

npm install @scaleflex/react-url-builder
# or
yarn add @scaleflex/react-url-builder

Peer dependencies

This package declares the following peers — install them in your host app:

• react ^18.3.1
• react-dom ^18.3.1
• @scaleflex/ui ^2.10.32
• @scaleflex/icons ^2.10.33
• styled-components ^6.1.13

Usage

import { UrlBuilder } from '@scaleflex/react-url-builder';

export default function Editor() {
  return (
    <UrlBuilder
      url="https://doc.cloudimg.io/sample.li/face.png"
      urlTitle="Parameters"
      headerTitle="Advanced builder"
      getGeneratedUrl={(url) => console.log('current url:', url)}
      onSave={(url) => console.log('user saved:', url)}
    />
  );
}

Props

| Prop | Type | Default | Description | | --- | --- | --- | --- | | url | string | '' | Source image URL. Legacy params (width=, height=, grey=) are auto-renamed to their modern equivalents. | | tabs | string[] | [] (shows all tabs) | Restrict which tabs are visible. Allowed values: 'format', 'adjust', 'position', 'finetune', 'filter', 'ai tools', 'watermarks'. | | getGeneratedUrl | (url: string) => void | — | Called with the current generated URL whenever it changes. | | onSave | (params: Record<string, string>, url: string) => void | — | Called when the user clicks the save button. params is the parsed query-param map (wat_url* values are already base64-encoded); url is the full generated URL string. | | onClose | () => void | — | Close handler. When provided, the builder also renders without an outer border (suitable for use inside a modal). | | urlTitle | string | — | Label shown above the URL preview. | | headerTitle | string | — | Interpolated into the header title translation (urlBuilderHeaderActionTitle). | | actionButtonLabel | string | — | Label for the save button. Falls back to the translated default when empty. | | language | string | 'en' | i18next language code for the bundled translations. | | withExtraParams | boolean | false | Preserve non-Cloudimage query params from the incoming URL instead of stripping them. | | withWatermark | boolean | false | When the incoming URL contains wat_text or wat_url params, rewrites them into the indexed form (wat_url[1], wat_text[2], etc.) expected by Filerobot. | | imageInfo | { width, height } \| { img_w, img_h } | {} | Source image dimensions. { width, height } is auto-remapped to { img_w, img_h }. Used to drive the preview and aspect-ratio logic. | | checkValueChanged | (changed: boolean) => void | — | Fires with true when the current URL's query string differs from the initial one. | | onChangeImage | (url: string) => void | — | Called with the current URL when the user clicks the "change image" button in the header. When omitted, the button is hidden. | | isSaving | boolean | — | Puts the save button in a loading state. |

License

See the license file in the repository.