JSCAD Parameters

Create dynamic, parametric designs that can be easily customized through user-friendly controls.

What are Parameters?

Parameters allow you to create flexible designs that can be modified without changing code. STL.Show automatically generates user interface controls based on your parameter definitions, making it easy for anyone to customize your designs.

Dynamic Controls

Automatic UI generation for easy customization

Real-time Updates

See changes instantly as you adjust parameters

Persistent Values

Parameter values are saved with your project

Basic Parameter Structure

Parameters are defined using the getParameterDefinitions() function and accessed in your main() function.

const { cube, sphere } = require('@jscad/modeling').primitives

// Define parameters
function getParameterDefinitions() {
  return [
    {name: 'size', type: 'number', initial: 10, caption: 'Size'},
    {name: 'segments', type: 'number', initial: 16, caption: 'Segments'}
  ]
}

// Use parameters in main function
function main(params) {
  return cube({size: params.size})
}

module.exports = { main, getParameterDefinitions }

Parameter Definition

• name - Unique identifier for the parameter
• type - Data type (number, choice, text, etc.)
• initial - Default value
• caption - Display label in UI

Parameter Usage

• Parameters are passed to main(params)
• Access values using params.parameterName
• Use in any calculation or geometry creation
• Changes trigger automatic recompilation

Parameter Types

JSCAD supports various parameter types, each with different UI controls and validation options.

Number

Numeric values with optional constraints and step increments.

Basic Usage

{name: 'size', type: 'number', initial: 10, caption: 'Size'}

With Constraints

{
  name: 'radius',
  type: 'number',
  initial: 5,
  min: 1,
  max: 20,
  step: 0.5,
  caption: 'Radius'
}

Features: Min/max constraints, step increments, real-time validation

Choice

Dropdown selection from predefined options.

Basic Usage

{
  name: 'shape',
  type: 'choice',
  values: ['cube', 'sphere', 'cylinder'],
  captions: ['Cube', 'Sphere', 'Cylinder'],
  initial: 'cube',
  caption: 'Shape Type'
}

Simple Options

{
  name: 'quality',
  type: 'choice',
  values: ['low', 'medium', 'high'],
  initial: 'medium',
  caption: 'Quality'
}

Features: Dropdown selection, custom captions, value mapping

Text

String input for text-based parameters.

Basic Usage

{
  name: 'label',
  type: 'text',
  initial: 'My Design',
  caption: 'Design Label'
}

With Validation

{
  name: 'filename',
  type: 'text',
  initial: 'design',
  maxLength: 20,
  caption: 'File Name'
}

Features: Text input, length validation, placeholder text

Checkbox

Boolean true/false values for enabling/disabling features.

Basic Usage

{
  name: 'showHoles',
  type: 'checkbox',
  checked: true,
  caption: 'Show Holes'
}

Conditional Logic

// In main function
if (params.showHoles) {
  // Add holes to design
}

Features: Boolean values, conditional logic, feature toggles

Color

Color picker for applying colors to geometry.

Basic Usage

{
  name: 'objectColor',
  type: 'color',
  initial: '#ff0000',
  caption: 'Object Color'
}

Apply Color

// In main function
return color(params.objectColor, cube({size: 10}))

Features: Color picker, hex values, visual preview

Advanced Parameter Features

Advanced techniques for creating sophisticated parametric designs.

Parameter Groups

Organize parameters into logical groups for better UI organization.

function getParameterDefinitions() {
  return [
    // Basic parameters
    {name: 'size', type: 'number', initial: 10, caption: 'Size'},
    
    // Group: Hole settings
    {name: 'holeDiameter', type: 'number', initial: 2, caption: 'Hole Diameter'},
    {name: 'holeDepth', type: 'number', initial: 5, caption: 'Hole Depth'},
    
    // Group: Material settings
    {name: 'material', type: 'choice', values: ['plastic', 'metal'], initial: 'plastic', caption: 'Material'},
    {name: 'thickness', type: 'number', initial: 1, caption: 'Wall Thickness'}
  ]
}

Tip: Use comments to visually group related parameters in your code.

Conditional Parameters

Show/hide parameters based on other parameter values.

Parameter Definition

function getParameterDefinitions() {
  return [
    {name: 'shape', type: 'choice', values: ['cube', 'sphere'], initial: 'cube', caption: 'Shape'},
    {name: 'cubeSize', type: 'number', initial: 10, caption: 'Cube Size'},
    {name: 'sphereRadius', type: 'number', initial: 5, caption: 'Sphere Radius'}
  ]
}

Conditional Logic

function main(params) {
  if (params.shape === 'cube') {
    return cube({size: params.cubeSize})
  } else {
    return sphere({radius: params.sphereRadius})
  }
}

Note: STL.Show will show/hide parameter controls based on conditional logic.

Parameter Validation

Ensure parameter values are within acceptable ranges and relationships.

function main(params) {
  // Validate parameters
  if (params.innerRadius >= params.outerRadius) {
    throw new Error('Inner radius must be smaller than outer radius')
  }
  
  if (params.height <= 0) {
    throw new Error('Height must be positive')
  }
  
  // Create geometry
  return cylinder({
    radius: params.outerRadius,
    height: params.height
  })
}

Tip: Use validation to prevent invalid geometry and provide helpful error messages.

Complete Parameter Example

A comprehensive example showing various parameter types and advanced features.

const { cube, sphere, cylinder } = require('@jscad/modeling').primitives
const { translate, rotate } = require('@jscad/modeling').transforms
const { union, subtract } = require('@jscad/modeling').booleans
const { color } = require('@jscad/modeling').colors

function getParameterDefinitions() {
  return [
    // Basic settings
    {name: 'objectType', type: 'choice', values: ['cube', 'sphere', 'cylinder'], 
     captions: ['Cube', 'Sphere', 'Cylinder'], initial: 'cube', caption: 'Object Type'},
    
    // Size parameters
    {name: 'size', type: 'number', initial: 10, min: 1, max: 50, step: 1, caption: 'Size'},
    {name: 'height', type: 'number', initial: 10, min: 1, max: 50, step: 1, caption: 'Height'},
    
    // Hole settings
    {name: 'hasHole', type: 'checkbox', checked: true, caption: 'Add Hole'},
    {name: 'holeDiameter', type: 'number', initial: 2, min: 0.5, max: 8, step: 0.5, caption: 'Hole Diameter'},
    {name: 'holeDepth', type: 'number', initial: 5, min: 1, max: 20, step: 1, caption: 'Hole Depth'},
    
    // Appearance
    {name: 'objectColor', type: 'color', initial: '#4f46e5', caption: 'Object Color'},
    {name: 'quality', type: 'choice', values: ['low', 'medium', 'high'], 
     captions: ['Low (8 segments)', 'Medium (16 segments)', 'High (32 segments)'], 
     initial: 'medium', caption: 'Quality'},
    
    // Text label
    {name: 'label', type: 'text', initial: 'My Design', maxLength: 20, caption: 'Label'}
  ]
}

function main(params) {
  // Determine segments based on quality
  const segments = params.quality === 'low' ? 8 : params.quality === 'medium' ? 16 : 32
  
  // Create base object
  let baseObject
  switch (params.objectType) {
    case 'cube':
      baseObject = cube({size: params.size})
      break
    case 'sphere':
      baseObject = sphere({radius: params.size / 2, segments})
      break
    case 'cylinder':
      baseObject = cylinder({radius: params.size / 2, height: params.height, segments})
      break
  }
  
  // Add hole if requested
  if (params.hasHole) {
    const hole = cylinder({
      radius: params.holeDiameter / 2,
      height: params.holeDepth,
      segments
    })
    baseObject = subtract(baseObject, hole)
  }
  
  // Apply color
  const coloredObject = color(params.objectColor, baseObject)
  
  return coloredObject
}

module.exports = { main, getParameterDefinitions }

Define parameters with types and constraints

Use parameters in geometry creation

Apply conditional logic and validation

Best Practices

Guidelines for creating effective and user-friendly parametric designs.

Parameter Naming

• Use descriptive, camelCase names
• Avoid generic names like 'value' or 'param'
• Group related parameters with prefixes
• Use consistent naming conventions

Default Values

• Choose sensible defaults that work well
• Consider typical use cases
• Avoid extreme values as defaults
• Test defaults with your geometry

Constraints

• Set min/max values to prevent errors
• Use step values for precision control
• Consider relationships between parameters
• Validate complex relationships in code

User Experience

• Use clear, descriptive captions
• Group related parameters together
• Provide helpful choice labels
• Keep parameter count reasonable

Ready to Create Parametric Designs?

Now that you understand parameters, explore these advanced topics:

Group Objects

Organize your designs with groups and child imports.

Code Editor

Master the integrated code editor and development tools.