Custom Style Parameters

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:

1. Navigate to the Playground tab in your template
2. Scroll to Style Parameters section
3. Click Add to create a new style parameter
4. Select the Parameter ID from the dropdown (with visual hints)
5. Select the Property to override (filtered by element type)
6. Enter a valid CSS Value
7. 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:

1. Detect Google Font names
2. Automatically load the font from Google Fonts
3. 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
  }
}

Important Notes#

Property Validation#

• Only valid CSS values are applied
• Invalid values are ignored (element uses default styles)
• Case-insensitive property names
• Aliases supported for common properties

Parameter ID Requirements#

• Must match an existing parameterized element
• Cannot contain . (dot) or @ symbols in the parameter ID itself
• Use the exact ID shown in the playground dropdown

Priority Order#

Style parameters have the highest priority:

1. Custom style parameters (highest)
2. Regular parameter values
3. Template default styles (lowest)

Performance#

• Style parameters are processed during render time
• Google Fonts are cached and loaded efficiently
• No performance impact on templates without style parameters

Best Practices#

Use Consistent Units: Stick to px, rem, or % for sizes

Test in Playground: Verify styles before production use

Document Your Styles: Keep a reference of available style parameters for your templates

Use Aliases: Leverage case-insensitive aliases for easier integration

Combine with Regular Parameters: Use both content and style parameters for maximum flexibility

Validate Input: In your application, validate CSS values before sending to API

Consider Fallbacks: Design templates with sensible defaults in case style parameters are invalid

Troubleshooting#

Style Not Applied#

• ✅ Check parameter ID matches exactly (case-sensitive for IDs)
• ✅ Verify property name is supported for that element type
• ✅ Ensure CSS value is valid (e.g., "24px" not "24")
• ✅ Test in playground first to isolate issues

Font Not Loading#

• ✅ Verify font name is correct (Google Fonts only)
• ✅ Check spelling and capitalization
• ✅ Ensure font supports your required weights
• ✅ Test with common fonts first (e.g., "Roboto", "Open Sans")

Multi-Page Issues#

• ✅ Use correct page prefix (e.g., page1@, page2@)
• ✅ Verify parameter exists on that specific page
• ✅ Check page number is correct (1-based indexing)