Control Types

Control types define the structure and configuration of form controls in Canvas Editor.

IControl

Main control interface combining all control properties.

src/editor/interface/Control.ts

type IControl = IControlBasic &
  IControlRule &
  Partial<IControlStyle> &
  Partial<IControlSelect> &
  Partial<IControlCheckbox> &
  Partial<IControlRadio> &
  Partial<IControlDate> &
  Partial<IControlNumber>

IControlBasic

Core control properties.

type

ControlType

required

Control type: TEXT, SELECT, CHECKBOX, RADIO, DATE, NUMBER

value

IElement[] | null

required

Control value as element array

placeholder

string

Placeholder text when empty

conceptId

string

Unique identifier for programmatic access

groupId

string

Group identifier for related controls

prefix

string

Text prefix before control

postfix

string

Text postfix after control

minWidth

number

Minimum control width in pixels

underline

boolean

Show underline

border

boolean

Show border

extension

unknown

Custom extension data

indentation

ControlIndentation

Content indentation mode: ROW_START or VALUE_START

rowFlex

RowFlex

Row alignment

preText

string

Text before control value

postText

string

Text after control value

IControlRule

Control behavior rules.

deletable

boolean

Whether control can be deleted

disabled

boolean

Whether control is disabled (readonly)

pasteDisabled

boolean

Whether paste is disabled in this control

hide

boolean

Whether control is hidden

IControlStyle

Control text styling.

font

string

Font family

size

number

Font size

bold

boolean

Bold text

highlight

string

Highlight color

italic

boolean

Italic text

strikeout

boolean

Strikethrough

Type-Specific Interfaces

IControlSelect

For SELECT controls (dropdowns).

src/editor/interface/Control.ts

interface IControlSelect {
  code: string | null
  valueSets: IValueSet[]
  isMultiSelect?: boolean
  multiSelectDelimiter?: string
  selectExclusiveOptions?: {
    inputAble?: boolean
  }
}

code

string | null

required

Selected option code

valueSets

IValueSet[]

required

Available options

isMultiSelect

boolean

Allow multiple selections

multiSelectDelimiter

string

Delimiter for multi-select values (default: ’,’)

selectExclusiveOptions

object

Additional options:

inputAble: Allow custom input

IValueSet

Option for SELECT controls.

src/editor/interface/Control.ts

interface IValueSet {
  value: string
  code: string
}

Example:

const options: IValueSet[] = [
  { value: 'United States', code: 'us' },
  { value: 'Canada', code: 'ca' },
  { value: 'Mexico', code: 'mx' }
]

IControlCheckbox

For CHECKBOX controls.

src/editor/interface/Control.ts

interface IControlCheckbox {
  code: string | null
  min?: number
  max?: number
  flexDirection: FlexDirection
  valueSets: IValueSet[]
}

code

string | null

required

Selected checkbox codes (comma-separated)

valueSets

IValueSet[]

required

Checkbox options

flexDirection

FlexDirection

required

Layout direction: ROW or COLUMN

min

number

Minimum selections required

max

number

Maximum selections allowed

IControlRadio

For RADIO controls.

src/editor/interface/Control.ts

interface IControlRadio {
  code: string | null
  flexDirection: FlexDirection
  valueSets: IValueSet[]
}

code

string | null

required

Selected radio code

valueSets

IValueSet[]

required

Radio button options

flexDirection

FlexDirection

required

Layout direction

IControlDate

For DATE controls.

src/editor/interface/Control.ts

interface IControlDate {
  dateFormat?: string
}

dateFormat

string

Date format string (e.g., ‘YYYY-MM-DD’, ‘MM/DD/YYYY’)

IControlNumber

For NUMBER controls.

src/editor/interface/Control.ts

interface IControlNumber {
  numberExclusiveOptions?: {
    calculatorDisabled?: boolean
  }
}

numberExclusiveOptions

object

calculatorDisabled: Disable built-in calculator

Control Examples

Text Control

import { ControlType } from '@hufe921/canvas-editor'

const textControl: IControl = {
  type: ControlType.TEXT,
  value: null,
  conceptId: 'firstName',
  placeholder: 'Enter your first name',
  minWidth: 200,
  prefix: 'Name: ',
  underline: true
}

editor.command.executeInsertControl(textControl)

Select Control

const selectControl: IControl = {
  type: ControlType.SELECT,
  value: null,
  conceptId: 'country',
  code: null,
  valueSets: [
    { value: 'United States', code: 'us' },
    { value: 'Canada', code: 'ca' },
    { value: 'United Kingdom', code: 'uk' }
  ],
  placeholder: 'Select a country'
}

editor.command.executeInsertControl(selectControl)

Checkbox Control

import { FlexDirection } from '@hufe921/canvas-editor'

const checkboxControl: IControl = {
  type: ControlType.CHECKBOX,
  value: null,
  conceptId: 'interests',
  code: null,
  valueSets: [
    { value: 'Sports', code: 'sports' },
    { value: 'Music', code: 'music' },
    { value: 'Reading', code: 'reading' }
  ],
  flexDirection: FlexDirection.COLUMN,
  min: 1,
  max: 2
}

editor.command.executeInsertControl(checkboxControl)

Radio Control

const radioControl: IControl = {
  type: ControlType.RADIO,
  value: null,
  conceptId: 'gender',
  code: null,
  valueSets: [
    { value: 'Male', code: 'm' },
    { value: 'Female', code: 'f' },
    { value: 'Other', code: 'o' }
  ],
  flexDirection: FlexDirection.ROW
}

editor.command.executeInsertControl(radioControl)

Date Control

const dateControl: IControl = {
  type: ControlType.DATE,
  value: null,
  conceptId: 'birthDate',
  dateFormat: 'YYYY-MM-DD',
  placeholder: 'Select date'
}

editor.command.executeInsertControl(dateControl)

Number Control

const numberControl: IControl = {
  type: ControlType.NUMBER,
  value: null,
  conceptId: 'age',
  placeholder: 'Enter age',
  minWidth: 100
}

editor.command.executeInsertControl(numberControl)

Working with Controls

Setting Control Values

// Set single value
editor.command.executeSetControlValue([{
  conceptId: 'firstName',
  value: 'John'
}])

// Set multiple values
editor.command.executeSetControlValue([
  { conceptId: 'firstName', value: 'John' },
  { conceptId: 'lastName', value: 'Doe' },
  { conceptId: 'country', value: 'us' }
])

// Set with rich text
editor.command.executeSetControlValue([{
  conceptId: 'notes',
  value: [
    { value: 'Important: ', bold: true },
    { value: 'Please review' }
  ]
}])

Getting Control Values

// Get all controls
const allControls = editor.command.getControlValue()

// Get specific control
const firstName = editor.command.getControlValue({ 
  conceptId: 'firstName' 
})

if (firstName.length > 0) {
  console.log('First name:', firstName[0].value)
}

// Get by group
const personalInfo = editor.command.getControlValue({ 
  groupId: 'personal' 
})

Updating Control Properties

// Make control readonly
editor.command.executeSetControlProperties([{
  conceptId: 'email',
  properties: {
    disabled: true,
    highlight: '#EEEEEE'
  }
}])

// Update placeholder
editor.command.executeSetControlProperties([{
  conceptId: 'phone',
  properties: {
    placeholder: '(555) 123-4567'
  }
}])

Control Events

// Listen for control activation
editor.eventBus.on('controlChange', ({ state, control, controlId }) => {
  if (state === 'active') {
    console.log(`Control ${control.conceptId} activated`)
  }
})

// Listen for value changes
editor.eventBus.on('controlContentChange', ({ control }) => {
  console.log(`Control ${control.conceptId} changed:`, control.value)
  
  // Validate
  if (control.conceptId === 'email') {
    validateEmail(control.value)
  }
})

IGetControlValueResult

Result type when getting control values.

src/editor/interface/Control.ts

type IGetControlValueResult = (Omit<IControl, 'value'> & {
  value: string | null
  innerText: string | null
  zone: EditorZone
  elementList?: IElement[]
})[]

Properties:

All control properties except value
value: Plain text value
innerText: Inner text content
zone: Location (HEADER, MAIN, or FOOTER)
elementList: Rich element representation

Example:

const controls = editor.command.getControlValue()

controls.forEach(control => {
  console.log(`ID: ${control.conceptId}`)
  console.log(`Value: ${control.value}`)
  console.log(`Zone: ${control.zone}`)
  console.log(`Type: ${control.type}`)
})

Editor Class

Commands

Events & Listeners

Types & Interfaces

Enums

Utilities

IControl

IControlBasic

IControlRule

IControlStyle

Type-Specific Interfaces

IControlSelect

IValueSet

IControlCheckbox

IControlRadio

IControlDate

IControlNumber

Control Examples

Text Control

Select Control

Checkbox Control

Radio Control

Date Control

Number Control

Working with Controls

Setting Control Values

Getting Control Values

Updating Control Properties

Control Events

IGetControlValueResult

Build docs developers (and LLMs) love

Editor Class

Commands

Events & Listeners

Types & Interfaces

Enums

Utilities

​IControl

​IControlBasic

​IControlRule

​IControlStyle

​Type-Specific Interfaces

​IControlSelect

​IValueSet

​IControlCheckbox

​IControlRadio

​IControlDate

​IControlNumber

​Control Examples

​Text Control

​Select Control

​Checkbox Control

​Radio Control

​Date Control

​Number Control

​Working with Controls

​Setting Control Values

​Getting Control Values

​Updating Control Properties

​Control Events

​IGetControlValueResult

Build docs developers (and LLMs) love

IControl

IControlBasic

IControlRule

IControlStyle

Type-Specific Interfaces

IControlSelect

IValueSet

IControlCheckbox

IControlRadio

IControlDate

IControlNumber

Control Examples

Text Control

Select Control

Checkbox Control

Radio Control

Date Control

Number Control

Working with Controls

Setting Control Values

Getting Control Values

Updating Control Properties

Control Events

IGetControlValueResult