Settings

Overview

Settings define the configurable public API for a component, allowing users to modify its behavior or appearance for different use cases without altering its internal code.

Defining Settings

Default settings are specified by passing a defaultSettings object when creating a component using defineComponent:

const defaultSettings = {
  name: 'Jack',
  color: 'blue',
  size: 'medium',
  count: 5
};

defineComponent({
  tagName: 'name-card',
  defaultSettings
});

A setting’s type is inferred from its default value, so you don’t need to explicitly declare types.

Settings vs. State

Settings represent the external API for your component, while state represents the internal configuration of your component.

For example, in a dropdown component:

• The list of options would be a setting (configured from outside)
• Whether the dropdown is currently open would be state (managed internally)

Specifying Settings

Users can override a component’s default settings in several ways:

HTML Attributes

The most common way to override settings is through HTML attributes:

<name-card name="Sally" color="red" size="large" count="10"></name-card>

JavaScript Properties

Settings can also be set directly as properties on the component’s DOM element:

const el = document.querySelector('name-card');
el.name = 'Sam';
el.color = 'green';

Using the Query Library

The Query library provides convenient methods for accessing components and updating their settings programmatically.

The settings() Method

Use the settings() method to set multiple properties on one or more components:

import { $ } from '@semantic-ui/query';

// Configure a single component
$('name-card').settings({
  name: 'Alex',
  color: 'purple'
});

// Configure multiple components at once
$('.user-cards name-card').settings({
  showAvatar: true,
  displayMode: 'compact'
});

The setting() Method

Use the setting() method to set a single property on one or more components:

import { $ } from '@semantic-ui/query';

// Set a single property
$('name-card').setting('name', 'Alex');

// Set a function property
$('user-form').setting('onSubmit', (data) => {
  saveUserData(data);
});

The initialize() Method

For components that need to be configured before they’re used, the initialize() method sets properties after the DOM is fully loaded:

import { $ } from '@semantic-ui/query';

// Wait for DOM to be ready, then set properties
$('name-card').initialize({
  onSelect: (value) => console.log('Selected:', value),
  formatter: (text) => text.toUpperCase()
});

This is especially useful for passing function references that can’t be serialized as HTML attributes.

Data Types

Different data types require different handling when passed as settings:

Strings and Numbers

Pass strings and numbers directly via HTML attributes or JavaScript properties:

<price-display amount="99.99" currency="USD"></price-display>

Complex Types (Objects, Arrays, Dates)

When passing complex types via HTML attributes, serialize them using JSON:

<user-list users='[{"name":"Alex","role":"admin"},{"name":"Sam","role":"user"}]'></user-list>

When setting complex types via JavaScript properties, pass the object or array directly:

const userList = $('user-list').setting(users, [
  { name: 'Alex', role: 'admin' },
  { name: 'Sam', role: 'user' }
]);

Functions

Functions cannot be serialized as HTML attributes and must be passed via JavaScript properties:

$('user-form').setting('onSubmit', (data) => {
  saveUserData(data);
};

Putting It All Together

In the following example, Query is used to modify the runtime settings of a component using settings()

• Several settings are overridden with properties in page.js.
  • getName() is overridden to return Sam instead of Jill
  • Birthday is overridden to January 2
• Several settings are overridden in attributes in page.html
  • Siblings is modified to be ["Tom", "Jerry"]
  • Job Age and Married are also modified
• page.js also attaches an event listener to a link to modify the settings again when the “change birthday” link is clicked