# Trait Manager
In GrapesJS, Traits define different parameters and behaviors of a component. Users generally see traits as a component's Settings. A common use of traits is to customize element attributes (e.g., placeholder for <input>). You can also bind traits to component properties and react to their changes.
WARNING
This guide applies to GrapesJS v0.21.9 or higher.
To better understand this guide, we recommend reading Components first.
TIP
Want traits that look great and work out of the box? See how the Grapes Studio SDK handles it. (opens new window)
# Add Traits to Components
Generally, you define traits as part of a custom component definition or by extending an existing component type. Let's see how to make inputs more customizable in the editor.
All components, by default, contain two traits: id and title (at the time of writing). So, if you select an input and open the Settings panel, you will see this:
We can start by creating a new custom input component in this way:
editor.Components.addType('input', {
isComponent: (el) => el.tagName === 'INPUT',
model: {
defaults: {
traits: [
// Strings are automatically converted to text types
'name', // Same as: { type: 'text', name: 'name' }
'placeholder',
{
type: 'select', // Type of the trait
name: 'type', // (required) The name of the attribute/property to use on the component
label: 'Type', // The label you will see in Settings
options: [
{ id: 'text', label: 'Text' },
{ id: 'email', label: 'Email' },
{ id: 'password', label: 'Password' },
{ id: 'number', label: 'Number' },
],
},
{
type: 'checkbox',
name: 'required',
},
],
// Traits are bound to attributes by default, so we can use
// attributes to define their initial values
attributes: { type: 'text', required: true },
},
},
});
The result will be:
You can also use a function to define traits dynamically during component initialization. This is useful if you need to create traits based on other component characteristics.
editor.Components.addType('input', {
isComponent: (el) => el.tagName === 'INPUT',
model: {
defaults: {
traits(component) {
const result = [];
// Example of some logic
if (component.get('draggable')) {
result.push('name');
} else {
result.push({
type: 'select',
// ....
});
}
return result;
},
},
},
});
To react to trait changes, you can listen for changes to the corresponding attributes:
editor.Components.addType('input', {
model: {
defaults: {
// ...
},
init() {
this.on('change:attributes:type', this.handleTypeChange);
},
handleTypeChange() {
console.log('Input type changed to: ', this.getAttributes().type);
},
},
});
As already mentioned, by default, traits modify attributes of the model, but you can also bind them to the properties by using the changeProp option.
editor.Components.addType('input', {
model: {
defaults: {
// ...
traits: [
{
name: 'placeholder',
changeProp: 1,
},
// ...
],
// As we switched from attributes to properties, the
// initial value should be set from the property
placeholder: 'Initial placeholder',
},
init() {
// The listener also changes from `change:attributes:*` to `change:*`
this.on('change:placeholder', this.handlePlhChange);
},
// ...
},
});
# Categories
It's possible to group your traits into categories, as shown below.
const category1 = { id: 'first', label: 'First category' };
const category2 = { id: 'second', label: 'Second category', open: false };
editor.Components.addType('input', {
model: {
defaults: {
// ...
traits: [
{ name: 'trait-1', category: category1 },
{ name: 'trait-2', category: category1 },
{ name: 'trait-3', category: category2 },
{ name: 'trait-4', category: category2 },
// Traits without categories will be rendered at the bottom
{ name: 'trait-5' },
{ name: 'trait-6' },
],
},
},
});
# Built-in trait types
GrapesJS comes with a few built-in types that you can use to define your traits:
# Text
Simple text input
{
type: 'text', // If you don't specify the type, `text` is the default
name: 'my-trait', // Required and available for all traits
label: 'My trait', // The label you will see near the input
// label: false, // If you set label to `false`, the label column will be removed
placeholder: 'Insert text', // Placeholder to show inside the input
}
# Number
Input for numbers
{
type: 'number',
// ...
placeholder: '0-100',
min: 0, // Minimum number value
max: 100, // Maximum number value
step: 5, // Number of steps
}
# Checkbox
Simple checkbox input
{
type: 'checkbox',
// ...
valueTrue: 'YES', // Value to assign when checked, default: `true`
valueFalse: 'NO', // Value to assign when unchecked, default: `false`
}
# Select
Select input with options
{
type: 'select',
// ...
options: [ // Array of options
{ id: 'opt1', label: 'Option 1'},
{ id: 'opt2', label: 'Option 2'},
]
}
# Color
Color picker
{
type: 'color',
// ...
}
# Button
Button with a command to assign
{
type: 'button',
// ...
text: 'Click me',
full: true, // Full width button
command: editor => alert('Hello'),
// or you can just specify the Command ID
command: 'some-command',
}
# Updating traits at run-time
To change a trait on your component, use the Component API:
Traits are stored as a property of the component. To get the complete list of current traits, use this:
const component = editor.getSelected(); // Component selected in canvas
const traits = component.get('traits');
traits.forEach((trait) => console.log(trait.props()));
In case you need a single one:
const component = editor.getSelected();
console.log(component.getTrait('type').props()); // Finds by the `name` of the trait
To update a property of the trait, do this:
// Let's update `options` of our `type` trait, defined in Input component
const component = editor.getSelected();
component.getTrait('type').set('options', [
{ id: 'opt1', label: 'New option 1'},
{ id: 'opt2', label: 'New option 2'},
]);
// or with multiple values
component.getTrait('type').set({
label: 'My type',
options: [...],
});
You can also add or remove traits using addTrait/removeTrait.
// Add new trait
const component = editor.getSelected();
component.addTrait({
name: 'type',
...
}, { at: 0 });
// The `at` option specifies the index at which to place the new trait;
// without it, the trait will be appended at the end of the list
// Remove trait
component.removeTrait('type');
# I18n
To use the I18n module, follow this schema:
{
en: {
traitManager: {
empty: 'Select an element before using Trait Manager',
label: 'Component settings',
categories: {
categoryId: 'Category label',
},
traits: {
// The trait `name` property is used as a key
labels: {
href: 'Href label',
},
// For built-in traits, like `text` type, these are used on input DOM attributes
attributes: {
href: { placeholder: 'eg. https://google.com' },
},
// For `select` types, these are used to translate option labels
options: {
target: {
// Here the key is the `id` of the option
_blank: 'New window',
},
},
},
},
}
}
# Customization
The default types cover most common properties. If you need a more advanced UI, you can define your own types or create a completely custom Trait Manager UI from scratch.
# Define new Trait type
For most cases, the default types should be enough, but sometimes you might need something more. In that case, you can define a new type of trait and bind any kind of element to it.
# Create element
Let's update the default link Component with a new kind of trait. These are the default traits for a simple link:
Let's just replace all of its traits with a new one, href-next, which will allow the user to select the type of href (e.g., 'url', 'email', etc.).
// Update component
editor.Components.addType('link', {
model: {
defaults: {
traits: [
{
type: 'href-next',
name: 'href',
label: 'New href',
},
],
},
},
});
Now you'll see a simple text input because we have not yet defined our new trait type, so let's do it:
editor.Traits.addType('href-next', {
// Should return a simple HTML string or an HTML element
createInput({ trait }) {
// Here we can decide to use properties from the trait
const traitOpts = trait.get('options') || [];
const options = traitOpts.length
? traitOpts
: [
{ id: 'url', label: 'URL' },
{ id: 'email', label: 'Email' },
];
// Create a new element container and add some content
const el = document.createElement('div');
el.innerHTML = `
<select class="href-next__type">
${options.map((opt) => `<option value="${opt.id}">${opt.label}</option>`).join('')}
</select>
<div class="href-next__url-inputs">
<input class="href-next__url" placeholder="Insert URL"/>
</div>
<div class="href-next__email-inputs">
<input class="href-next__email" placeholder="Insert email"/>
<input class="href-next__email-subject" placeholder="Insert subject"/>
</div>
`;
// Let's make our content interactive
const inputsUrl = el.querySelector('.href-next__url-inputs');
const inputsEmail = el.querySelector('.href-next__email-inputs');
const inputType = el.querySelector('.href-next__type');
inputType.addEventListener('change', (ev) => {
switch (ev.target.value) {
case 'url':
inputsUrl.style.display = '';
inputsEmail.style.display = 'none';
break;
case 'email':
inputsUrl.style.display = 'none';
inputsEmail.style.display = '';
break;
}
});
return el;
},
});
In the example above, we created custom inputs, allowing the use of the option trait property, and added logic to switch inputs when the type changes. The result looks like this:
# Update layout
Before making our trait work, let's look at its layout. You might have noticed that a trait consists of label and input columns. GrapesJS allows you to customize both.
To customize the label, use createLabel:
editor.Traits.addType('href-next', {
// Should return a simple HTML string or an HTML element
createLabel({ label }) {
return `<div>
<div>Before</div>
${label}
<div>After</div>
</div>`;
},
// ...
});
You've already seen that you can set label: false in a trait definition to remove the label column. To apply this behavior to all instances of a trait type, use the noLabel property:
editor.Traits.addType('href-next', {
noLabel: true,
// ...
});
By default, GrapesJS adds a wrapper around your inputs. This works well for simple inputs but may not suit a complex custom trait. To remove the default wrapper, use the templateInput option:
editor.Traits.addType('href-next', {
// Completely remove the wrapper
templateInput: '',
// Use a new wrapper, specifying where to place the input container with the `data-input` attribute
templateInput: `<div class="custom-input-wrapper">
Before input
<div data-input></div>
After input
</div>`,
// It can also be a function that returns an HTML string
templateInput({ trait }) {
return '<div ...';
},
});
In this case, the result is unstyled, but custom trait types allow you to reuse your own styled inputs, which you may have already designed or implemented in a UI framework. For now, let's keep the default input wrapper and continue with the integration of our custom trait.
# Bind to component
The element created in createInput is not yet bound to the component, so nothing happens when you update the inputs. Let's bind it now:
editor.Traits.addType('href-next', {
// ...
// Update the component based on element changes
// `elInput` is the result HTMLElement you get from `createInput`
onEvent({ elInput, component, event }) {
const inputType = elInput.querySelector('.href-next__type');
let href = '';
switch (inputType.value) {
case 'url':
const valUrl = elInput.querySelector('.href-next__url').value;
href = valUrl;
break;
case 'email':
const valEmail = elInput.querySelector('.href-next__email').value;
const valSubj = elInput.querySelector('.href-next__email-subject').value;
href = `mailto:${valEmail}${valSubj ? `?subject=${valSubj}` : ''}`;
break;
}
component.addAttributes({ href });
},
});
Most of the trait should now work (you can update it and check the HTML in the code preview). You might wonder how the editor captures input changes and how to control this.
By default, the base trait wrapper listens for the change event and calls onEvent for each captured event. To be captured, the event must bubble (opens new window). To update the component on the input event instead, change the eventCapture property:
editor.Traits.addType('href-next', {
eventCapture: ['input'], // you can use multiple events in the array
// ...
});
Finally, you might have noticed that the inputs are not initially populated when the component already has an href attribute. Handle this in the onUpdate method:
editor.Traits.addType('href-next', {
// ...
// Update elements on the component change
onUpdate({ elInput, component }) {
const href = component.getAttributes().href || '';
const inputType = elInput.querySelector('.href-next__type');
let type = 'url';
if (href.indexOf('mailto:') === 0) {
const inputEmail = elInput.querySelector('.href-next__email');
const inputSubject = elInput.querySelector('.href-next__email-subject');
const mailTo = href.replace('mailto:', '').split('?');
const email = mailTo[0];
const params = (mailTo[1] || '').split('&').reduce((acc, item) => {
const items = item.split('=');
acc[items[0]] = items[1];
return acc;
}, {});
type = 'email';
inputEmail.value = email || '';
inputSubject.value = params.subject || '';
} else {
elInput.querySelector('.href-next__url').value = href;
}
inputType.value = type;
inputType.dispatchEvent(new CustomEvent('change'));
},
});
Now the trait will also update when the component changes, for example:
editor.getSelected().addAttributes({ href: 'mailto:new-email@test.com?subject=NewSubject' });
To create a custom trait type, you need three methods:
createInput- Where we define our custom HTML elementonEvent- How to update the component when inputs changeonUpdate- How to update inputs on component changes
# Result
You can see the final result here:
# Integrate external UI components
The example above might seem like a lot of code, but most of it handles the native DOM API, with only a little additional logic. A modern UI framework (e.g., Vue or React) can make integration easier. Here's how to integrate a custom Vue Slider Component (opens new window) as a trait:
editor.Traits.addType('slider', {
createInput({ trait }) {
const vueInst = new Vue({ render: (h) => h(VueSlider) }).$mount();
const sliderInst = vueInst.$children[0];
sliderInst.$on('change', (ev) => this.onChange(ev)); // Use onChange to trigger onEvent
this.sliderInst = sliderInst;
return vueInst.$el;
},
onEvent({ component }) {
const value = this.sliderInst.getValue() || 0;
component.addAttributes({ value });
},
onUpdate({ component }) {
const value = component.getAttributes().value || 0;
this.sliderInst.setValue(value);
},
});
The integration with external components is possible by following these key steps:
- Component rendering:
new Vue({ render: ...
This depends on the framework. For example, in React it would beReactDOM.render(element, ... - Change propagation:
sliderInst.$on('change', ev => this.onChange(ev))
The framework should have a mechanism to subscribe to changes and the component should expose that change (opens new window)
We've also used theonChangemethod, which is useful when you need to triggeronEventmanually. Always callonEventthroughonChangerather than directly. - Property getters/setters:
sliderInst.getValue()(opens new window)/sliderInst.setValue(value)(opens new window)
The component should allow you to read and write data through the instance.
# Custom Trait Manager
The default Trait Manager UI handles most common tasks. If you need more advanced logic or elements, you can create your own UI from scratch.
Tell the editor to use a custom UI, then subscribe to the trait:custom event, which is triggered whenever the UI needs to update.
const editor = grapesjs.init({
// ...
traitManager: {
custom: true,
// ...
},
});
editor.on('trait:custom', (props) => {
// props.container (HTMLElement) - The default element where you can append your custom UI
// Here you would put the logic to render/update your UI.
});
In the example below, we'll replicate most of the default functionality by using the Traits API.
# Events
For a complete list of available events, check here.