Custom Elements

Create your own element types for specialized inputs beyond the built-in types.

Advanced Feature: Custom element types require HTML/CSS knowledge and use render functions that return HTML strings. For most use cases, the built-in element types should be sufficient.

Overview

Custom elements allow you to:

Create specialized form inputs
Build complex UI components
Implement custom validation
Add unique interactions

Creating a Custom Element

Step 1: Define the Render Function

Custom elements use a render function that returns an HTML string.

const colorPickerRenderer = (element, value, uniqueId) => {
  const currentValue = value || element.default || '#000000';
  
  return `
    <div class="settings-input-group" data-element-id="${element.id}">
      <label for="${uniqueId}">
        ${element.label}
        ${element.required ? '<span style="color: var(--col-danger)"> *</span>' : ''}
      </label>
      
      ${element.description ? `<p class="settings-description">${element.description}</p>` : ''}
      
      <div style="display: flex; align-items: center; gap: 10px;">
        <input
          type="color"
          id="${uniqueId}-color"
          value="${currentValue}"
          onchange="this.nextElementSibling.value = this.value; this.dispatchEvent(new CustomEvent('setting-changed', {detail: {id: '${element.id}', value: this.value}, bubbles: true}));"
          style="width: 60px; height: 40px; cursor: pointer;"
        />
        <input
          type="text"
          id="${uniqueId}"
          value="${currentValue}"
          placeholder="#000000"
          oninput="this.previousElementSibling.value = this.value; this.dispatchEvent(new CustomEvent('setting-changed', {detail: {id: '${element.id}', value: this.value}, bubbles: true}));"
          style="flex: 1; padding: 8px 12px; background-color: var(--col-input-default); border: 1px solid var(--col-ouliner-default); border-radius: var(--radius-sm); color: var(--col-txt-primary);"
        />
      </div>
      
      ${element.hint ? `<small style="color: var(--col-txt-secondary); font-size: 12px;">${element.hint}</small>` : ''}
    </div>
  `;
};

Step 2: Register the Element Type

api.nexomaker.postSettingsElementType(
  'color-picker',      // Type identifier
  colorPickerRenderer, // Render function
  'both'              // Target: 'app', 'project', or 'both'
);

Step 3: Use in Settings

api.nexomaker.postAppSettingsTab({
  id: "theme-settings",
  title: "Theme",
  elements: [
    {
      id: "primary-color",
      label: "Primary Color",
      type: "color-picker", // Your custom type
      description: "Main brand color",
      default: "#3b82f6"
    },
    {
      id: "secondary-color",
      label: "Secondary Color",
      type: "color-picker",
      default: "#8b5cf6"
    }
  ]
});

Render Function Reference

Parameters

Parameter

Type

Description

element

Object

The element configuration object with id, label, type, default, etc.

value

Any

Current value of the element

uniqueId

String

Unique ID for DOM elements (use for input IDs)

Return Value

Must return a string containing HTML that will be inserted into the DOM.

Event Handling

To update values, dispatch a custom event from your input:

// Dispatch when value changes
this.dispatchEvent(new CustomEvent('setting-changed', {
  detail: { id: '${element.id}', value: newValue },
  bubbles: true
}));

Example with Event

const simpleTextRenderer = (element, value, uniqueId) => {
  return `
    <input
      type="text"
      id="${uniqueId}"
      value="${value || element.default || ''}"
      oninput="this.dispatchEvent(new CustomEvent('setting-changed', {detail: {id: '${element.id}', value: this.value}, bubbles: true}));"
    />
  `;
};

Examples

Simple Rating Element

const ratingRenderer = (element, value, uniqueId) => {
  const currentValue = value || element.default || 0;
  const maxRating = element.max || 5;
  
  let stars = '';
  for (let i = 1; i <= maxRating; i++) {
    const filled = i <= currentValue ? '★' : '☆';
    stars += `<span 
      onclick="this.parentElement.dispatchEvent(new CustomEvent('setting-changed', {detail: {id: '${element.id}', value: ${i}}, bubbles: true})); this.parentElement.querySelectorAll('span').forEach((s, idx) => s.textContent = idx < ${i} ? '★' : '☆');"
      style="font-size: 24px; cursor: pointer; color: var(--col-primary-form);"
    >${filled}</span>`;
  }
  
  return `
    <div class="settings-input-group">
      <label>${element.label}</label>
      ${element.description ? `<p class="settings-description">${element.description}</p>` : ''}
      <div id="${uniqueId}" style="padding: 8px 0;">${stars}</div>
    </div>
  `;
};

// Register it
api.nexomaker.postSettingsElementType('rating', ratingRenderer, 'both');

// Use it
api.nexomaker.postAppSettingsTab({
  id: "preferences",
  title: "Preferences",
  elements: [
    {
      id: "user-rating",
      label: "Rate this app",
      type: "rating",
      max: 5,
      default: 0
    }
  ]
});

File Size Selector

const fileSizeRenderer = (element, value, uniqueId) => {
  const currentValue = value || element.default || 0;
  const units = ['KB', 'MB', 'GB'];
  
  return `
    <div class="settings-input-group">
      <label for="${uniqueId}">${element.label}</label>
      ${element.description ? `<p class="settings-description">${element.description}</p>` : ''}
      <div style="display: flex; gap: 8px;">
        <input
          type="number"
          id="${uniqueId}-num"
          value="${Math.floor(currentValue / 1024)}"
          min="0"
          oninput="updateFileSize_${uniqueId}()"
          style="flex: 1; padding: 8px; background: var(--col-input-default); border: 1px solid var(--col-ouliner-default); border-radius: var(--radius-sm); color: var(--col-txt-primary);"
        />
        <select
          id="${uniqueId}-unit"
          onchange="updateFileSize_${uniqueId}()"
          style="padding: 8px; background: var(--col-input-default); border: 1px solid var(--col-ouliner-default); border-radius: var(--radius-sm); color: var(--col-txt-primary);"
        >
          ${units.map(u => `<option value="${u}">${u}</option>`).join('')}
        </select>
      </div>
    </div>
    <script>
      window.updateFileSize_${uniqueId} = function() {
        const num = document.getElementById('${uniqueId}-num').value;
        const unit = document.getElementById('${uniqueId}-unit').value;
        const multiplier = unit === 'KB' ? 1024 : unit === 'MB' ? 1024*1024 : 1024*1024*1024;
        const bytes = num * multiplier;
        document.getElementById('${uniqueId}-num').dispatchEvent(new CustomEvent('setting-changed', {
          detail: {id: '${element.id}', value: bytes},
          bubbles: true
        }));
      };
    </script>
  `;
};

api.nexomaker.postSettingsElementType('file-size', fileSizeRenderer, 'both');

Tag Input

const tagInputRenderer = (element, value, uniqueId) => {
  const tags = value || element.default || [];
  const tagsArray = Array.isArray(tags) ? tags : [];
  
  return `
    <div class="settings-input-group">
      <label for="${uniqueId}">${element.label}</label>
      ${element.description ? `<p class="settings-description">${element.description}</p>` : ''}
      <div id="${uniqueId}-tags" style="display: flex; flex-wrap: wrap; gap: 8px; padding: 8px; background: var(--col-input-default); border: 1px solid var(--col-ouliner-default); border-radius: var(--radius-sm); min-height: 40px;">
        ${tagsArray.map((tag, idx) => `
          <span style="background: var(--col-primary-form); color: white; padding: 4px 8px; border-radius: 4px; display: flex; align-items: center; gap: 4px;">
            ${tag}
            <button onclick="removeTag_${uniqueId}(${idx})" style="background: none; border: none; color: white; cursor: pointer; padding: 0; font-size: 16px;">×</button>
          </span>
        `).join('')}
        <input
          type="text"
          id="${uniqueId}-input"
          placeholder="Add tag..."
          onkeydown="if(event.key === 'Enter') addTag_${uniqueId}(this.value, this)"
          style="flex: 1; min-width: 100px; background: none; border: none; color: var(--col-txt-primary); outline: none;"
        />
      </div>
    </div>
    <script>
      window.tags_${uniqueId} = ${JSON.stringify(tagsArray)};
      
      window.addTag_${uniqueId} = function(tag, input) {
        if (tag.trim()) {
          window.tags_${uniqueId}.push(tag.trim());
          input.value = '';
          input.dispatchEvent(new CustomEvent('setting-changed', {
            detail: {id: '${element.id}', value: window.tags_${uniqueId}},
            bubbles: true
          }));
          setTimeout(() => location.reload(), 100);
        }
      };
      
      window.removeTag_${uniqueId} = function(index) {
        window.tags_${uniqueId}.splice(index, 1);
        document.getElementById('${uniqueId}-input').dispatchEvent(new CustomEvent('setting-changed', {
          detail: {id: '${element.id}', value: window.tags_${uniqueId}},
          bubbles: true
        }));
        setTimeout(() => location.reload(), 100);
      };
    </script>
  `;
};

api.nexomaker.postSettingsElementType('tags', tagInputRenderer, 'both');

CSS Variables

Use these CSS variables for consistent theming:

--col-txt-primary      /* Primary text color */
--col-txt-secondary    /* Secondary/muted text color */
--col-input-default    /* Input background color */
--col-ouliner-default  /* Border color */
--col-primary-form     /* Accent color (pink) */
--col-accent-col       /* Accent background */
--col-danger           /* Error/danger color */
--radius-sm            /* Small border radius */
--radius-md            /* Medium border radius */

Example with Variables

const styledInputRenderer = (element, value, uniqueId) => {
  return `
    <div class="settings-input-group">
      <label for="${uniqueId}">${element.label}</label>
      <input
        type="text"
        id="${uniqueId}"
        value="${value || ''}"
        style="
          padding: 8px 12px;
          background: var(--col-input-default);
          border: 1px solid var(--col-ouliner-default);
          border-radius: var(--radius-sm);
          color: var(--col-txt-primary);
          width: 100%;
        "
      />
    </div>
  `;
};

Best Practices

1. Always Use uniqueId for Element IDs

// ✅ Good
id="${uniqueId}"

// ❌ Bad
id="${element.id}" // Can cause conflicts

2. Dispatch Events on Change

// ✅ Good
onchange="this.dispatchEvent(new CustomEvent('setting-changed', {...}));"

// ❌ Bad
onchange="updateValue(this.value)" // Won't save

3. Escape Values Properly

// ✅ Good
value="${(value || '').replace(/"/g, '&quot;')}"

// ❌ Bad
value="${value}" // Can break with quotes

4. Use CSS Variables

// ✅ Good
style="color: var(--col-txt-primary);"

// ❌ Bad
style="color: #cacaca;" // Won't adapt to themes

5. Provide Fallback Values

// ✅ Good
const currentValue = value || element.default || '';

// ❌ Bad
const currentValue = value; // Can be undefined

Troubleshooting

Element Not Rendering

Problem: Custom element doesn't appear.

Solutions:

Check that element is registered before use
Verify render function returns a string
Check for syntax errors in HTML

Values Not Saving

Problem: Changes don't persist.

Solutions:

Ensure setting-changed event is dispatched
Check event bubbles: bubbles: true
Verify element ID matches in event detail

Styling Issues

Problem: Element doesn't match theme.

Solutions:

Use CSS variables instead of hardcoded colors
Wrap in settings-input-group div
Test in both light and dark modes

Next Steps

See more examples →
Learn about best practices →
Read about reading settings →

PreviousElement Types NextPlugin Expansion

Last updated 4 months ago

hashtagOverview

hashtagCreating a Custom Element

hashtagStep 1: Define the Render Function

hashtagStep 2: Register the Element Type

hashtagStep 3: Use in Settings

hashtagRender Function Reference

hashtagParameters

hashtagReturn Value

hashtagEvent Handling

hashtagExample with Event

hashtagExamples

hashtagSimple Rating Element

hashtagFile Size Selector

hashtagTag Input

hashtagCSS Variables

hashtagExample with Variables

hashtagBest Practices

hashtag1. Always Use uniqueId for Element IDs

hashtag2. Dispatch Events on Change

hashtag3. Escape Values Properly

hashtag4. Use CSS Variables

hashtag5. Provide Fallback Values

hashtagTroubleshooting

hashtagElement Not Rendering

hashtagValues Not Saving

hashtagStyling Issues

hashtagNext Steps

Overview

Creating a Custom Element

Step 1: Define the Render Function

Step 2: Register the Element Type

Step 3: Use in Settings

Render Function Reference

Parameters

Return Value

Event Handling

Example with Event

Examples

Simple Rating Element

File Size Selector

Tag Input

CSS Variables

Example with Variables

Best Practices

1. Always Use uniqueId for Element IDs

2. Dispatch Events on Change

3. Escape Values Properly

4. Use CSS Variables

5. Provide Fallback Values

Troubleshooting

Element Not Rendering

Values Not Saving

Styling Issues

Next Steps