Custom Style Parameters

Override element styles dynamically using custom style parameters in Orshot Studio

Custom Style Parameters allow you to dynamically override individual CSS properties of parameterized elements at render time. While regular parameters control content (text, images), style parameters give you precise control over visual properties like colors, fonts, sizes, and more

Video Tutorial

How It Works

Custom style parameters use a dot notation format: parameterId.property

For example:

title.fontSize - Changes the font size of a text element with parameter ID "title"
logo.borderRadius - Changes the border radius of an image element with parameter ID "logo"
badge.fill - Changes the fill color of a shape element with parameter ID "badge"

Syntax Format

Single Page Templates

{
  "templateId": 123,
  "modifications": {
    "title": "Hello World",
    "title.fontSize": "48px",
    "title.color": "#ff0000",
    "title.fontFamily": "Roboto"
  }
}

Multi-Page Templates

For multi-page templates, use the page prefix:

{
  "templateId": 123,
  "modifications": {
    "page1@title": "Page 1 Title",
    "page1@title.fontSize": "48px",
    "page2@title": "Page 2 Title",
    "page2@title.color": "#0000ff"
  }
}

Supported Properties

Text Elements

Typography

fontSize - Font size (e.g., "24px", "2rem")
fontWeight - Font weight (e.g., "bold", "400", "700")
fontStyle - Font style (e.g., "italic", "normal")
fontFamily - Font family (Google Fonts supported)
lineHeight - Line height (e.g., "1.5", "24px")
letterSpacing - Letter spacing (e.g., "0.05em", "2px")

Alignment & Decoration

textAlign - Text alignment ("left", "center", "right")
verticalAlign - Vertical alignment ("top", "middle", "bottom")
textDecoration - Text decoration ("underline", "none")
textTransform - Text transform ("uppercase", "lowercase", "capitalize")

Colors & Effects

color - Text color (e.g., "#ff0000", "rgba(255, 0, 0, 0.5)")
backgroundColor (or background, bgColor, bg) - Text background color
backgroundRadius (or bgRadius) - Text background border radius
textStrokeWidth - Stroke width (e.g., "2px")
textStrokeColor - Stroke color

Shadows & Effects

dropShadowX - Shadow horizontal offset
dropShadowY - Shadow vertical offset
dropShadowBlur - Shadow blur radius
dropShadowColor - Shadow color
opacity - Element opacity (0 to 1)
filter - CSS filter effects

Image Elements

Layout

objectFit - Object fit ("contain", "cover", "fill")
objectPosition - Object position (e.g., "center center", "top left")

Border

borderRadius - Border radius (e.g., "10px", "50%")
borderWidth - Border width (e.g., "2px")
borderColor - Border color

Shadow

boxShadowX - Box shadow horizontal offset
boxShadowY - Box shadow vertical offset
boxShadowBlur - Box shadow blur radius
boxShadowColor - Box shadow color

Effects

opacity - Image opacity (0 to 1)
filter - CSS filter effects
dropShadowX, dropShadowY, dropShadowBlur, dropShadowColor - Drop shadow

Shape Elements

Colors

fill - Fill color (supports gradients)
stroke - Stroke color
strokeWidth - Stroke width

Border & Effects

borderRadius - Corner radius (for rectangles/circles)
opacity - Shape opacity (0 to 1)
dropShadowX, dropShadowY, dropShadowBlur, dropShadowColor - Drop shadow

Property Name Variations

Style parameters are case-insensitive and support common aliases:

{
  // All of these work for text background color:
  "title.backgroundColor": "#ffff00",
  "title.background": "#ffff00",
  "title.bgColor": "#ffff00",
  "title.bg": "#ffff00",
 
  // All of these work for font size:
  "title.fontSize": "24px",
  "title.fontsize": "24px",
  "title.FONTSIZE": "24px"
}

Testing in Playground

You can test custom style parameters directly in the Studio Playground:

Navigate to the Playground tab in your template
Scroll to Style Parameters section
Click Add to create a new style parameter
Select the Parameter ID from the dropdown (with visual hints)
Select the Property to override (filtered by element type)
Enter a valid CSS Value
Click Generate Image to see the result

Using with Dynamic URLs

Custom style parameters work seamlessly with Dynamic URLs:

https://api.orshot.com/v1/dynamic-url/example.jpg?title.fontSize=48px&title.color=%23ff0000

Note: URL-encode special characters (e.g., # becomes %23)

Using with API

Include style parameters in your API requests:

curl -X POST https://api.orshot.com/v1/images \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": 123,
    "modifications": {
      "title": "Dynamic Title",
      "title.fontSize": "48px",
      "title.color": "#ff0000",
      "title.fontFamily": "Playfair Display",
      "logo.borderRadius": "50%",
      "badge.fill": "linear-gradient(to right, #ff0000, #0000ff)"
    }
  }'

Google Fonts Support

Custom style parameters automatically load Google Fonts when specified:

{
  "title.fontFamily": "Playfair Display",
  "subtitle.fontFamily": "Roboto"
}

The system will:

Detect Google Font names
Automatically load the font from Google Fonts
Apply it to the element during rendering

Practical Examples

Dynamic Theming

{
  "templateId": 123,
  "data": {
    "name": "John Doe",
    "title.color": "#1e40af", // Brand blue
    "subtitle.color": "#64748b", // Brand gray
    "badge.fill": "#1e40af", // Match brand
    "logo.borderRadius": "10px" // Rounded style
  }
}

Personalized Styles

{
  "templateId": 123,
  "data": {
    "username": "@johndoe",
    "avatar": "https://example.com/avatar.jpg",
    "avatar.borderRadius": "50%", // Circular avatar
    "username.fontSize": "24px", // Larger name
    "username.fontWeight": "bold", // Bold emphasis
    "username.color": "#000000" // Black text
  }
}

Gradient Effects

{
  "templateId": 123,
  "modifications": {
    "title": "Welcome",
    "background.fill": "linear-gradient(135deg, #667eea 0%, #764ba2 100%)",
    "title.color": "#ffffff",
    "title.textStrokeWidth": "2px",
    "title.textStrokeColor": "#000000"
  }
}

Responsive Typography

{
  "templateId": 123,
  "data": {
    "quote": "Short quote",
    "author": "Author Name",
    "quote.fontSize": "36px", // Larger for short quote
    "quote.lineHeight": "1.4", // Comfortable reading
    "author.fontSize": "16px", // Smaller author
    "author.fontStyle": "italic" // Italic emphasis
  }
}