miniPaint Documentation

You can embed the miniPaint image editor into your own website or application using an <iframe>. The provided snippet ensures the editor takes up the full height of the viewport and maintains responsive width.

<iframe style="box-sizing:border-box; width:100%; height:100vh;" id="miniPaint" src="https://viliusle.github.io/miniPaint/" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>

miniPaint initializes its core modules (Layers, Tools, GUI, State, etc.) on the window load event. Once initialized, these modules are attached to the app instance and also exposed as global variables on the window object for external access or quick scripting.

Global Variables available on window:

• Layers: Instance of Base_layers_class
• AppConfig: The application configuration object
• State: Instance of Base_state_class
• FileOpen: Instance of File_open_class
• FileSave: Instance of File_save_class

Note: Accessing these variables before the load event has fired may result in undefined as they are instantiated inside the event listener.

miniPaint uses a plugin-based system for its tools. To add a new tool, create a JavaScript module in the tools/ directory. The GUI_tools_class automatically discovers and loads these modules using require.context.

Each tool module must export a default class that accepts a 2D canvas context in its constructor. To integrate with the GUI, your tool class should implement the following properties and methods:

• name: A string used as the internal identifier for the tool.
• load(): (Optional) A method called automatically after the tool is instantiated.
• on_update (via config): If defined in the tool's configuration, the GUI will call a specific method on your tool instance whenever an attribute (like size, color, or a boolean toggle) is changed by the user.

The File_save_class manages file saving and exporting. It supports both non-destructive saving (preserving layers and RAW data via JSON) and standard image exporting.

Supported Formats

• PNG: Portable Network Graphics
• JPG: JPG/JPEG Format
• WEBP: Weppy File Format
• GIF: Graphics Interchange Format
• BMP: Windows Bitmap
• TIFF: Tag Image File Format
• JSON: Full layers data (non-destructive)

Keyboard Shortcuts

• s: Triggers the standard Save (includes JSON option for layers).
• Shift + s: Triggers the Export (standard image formats only, excludes JSON).

Note: Shortcuts are ignored if the user is currently typing in an input field.

The Google_fonts_search_class allows users to search and select fonts from the Google Web Fonts API. To enable this feature, you must provide a Google Web Fonts API key in the application configuration.

Required Config Key:

• config.google_webfonts_key: Your Google API key for the Web Fonts API.

Tool attributes are defined in the config.TOOLS object. When a user interacts with the GUI (toggles, sliders, color pickers, or selects), the GUI_tools_class updates the tool's state and can trigger a callback.

To handle attribute changes in your custom tool, use the on_update property in your tool's configuration. This property should contain the name of a method on your tool instance. The GUI will call this method with an object containing the changed key and value.

Supported attribute types in the GUI:

• Boolean: Rendered as toggle buttons or icon buttons.
• Number: Rendered as numeric inputs with min, max, and step support.
• Select: Rendered as a dropdown menu (can use a static array or a values() function).
• Color: Rendered as a color picker (strings starting with #).

Use get_selection() to retrieve the current selection data object. This object contains the spatial properties of the selected area.

Returns: An object containing:

• x: x-coordinate
• y: y-coordinate
• width: width
• height: height

Use the following methods to inspect the current state of layers:

• get_layers(): Returns the full array of all layers.
• get_layer(id): Returns a specific layer object by its ID. If no ID is provided, it returns the currently active layer from config.layer.
• is_layer_empty(id): Returns true if the layer has no dimensions and no data.
• get_dimensions(): Returns an object containing the current canvas { width, height }.
• find_next(id) / find_previous(id): Returns the next or previous layer object in the sorted stack based on the provided ID.

The Text_editor_class manages the rendering and interactive editing of text layers. It handles keyboard, mouse, and touch controls, including text selection and cursor movement.

When initializing, you can provide an options object to customize the appearance of text selections and the padding of the editor.

Options:

• selectionBackgroundColor: Color for the text selection background (default: '#1C79C4').
• selectionTextColor: Color for the text selection foreground (default: '#FFFFFF').
• paddingVertical: Vertical offset from the top/left of the layer for cursor visibility.
• paddingHorizontal: Horizontal offset from the top/left of the layer for cursor visibility.