
Enter a search term above to see results...
Enter a search term above to see results...
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.
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 represent the external API for your component, while state represents the internal configuration of your component.
For example, in a dropdown component:
Users can override a component’s default settings in several ways:
The most common way to override settings is through HTML attributes:
<name-card name="Sally" color="red" size="large" count="10"></name-card>
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';
The Query library provides methods for accessing components and updating their settings programmatically.
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'});
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 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()});
Useful for passing function references that can’t be serialized as HTML attributes.
Different data types require different handling when passed as settings:
Pass strings and numbers directly via HTML attributes or JavaScript properties:
<price-display amount="99.99" currency="USD"></price-display>
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 cannot be serialized as HTML attributes and must be passed via JavaScript properties:
$('user-form').setting('onSubmit', (data) => { saveUserData(data);});
This example shows modifying component settings with Query: