Using the UI-lib

Important:
Using the old UI-lib? Contact your account manager to switch over to our new UI-lib. Learn more.
Overview

Use the UI-lib to create the App Settings panel for your site component. It works with React JSX, jQuery, and AngularJS.

Our starter template helps you get started – all you need to do is get the template and then customize it for your app.

Once your project is set up, get to know the specifics of how to use our UI-lib with your preferred language.

We’ll also explain how to use wix style parameters, so that you can save specific values inside the Wix site (instead of on your database). This is important for certain UI controls, like the color picker.

Get Started

Use our starter template to get started. We’ve already set up a widget and connected it to its settings panel, so you’ll see how these two components interact with each other.  

All you need to do is get the template and customize it for your app.

Here’s how to get started:

  1. Get node.js.
  2. Get one of these starter templates, depending on your preferred language:
  3. Update your app regularly so that you’re always using the latest dependencies.
Important:
Learn more about how our UI-lib works with ReactJSX, jQuery, and AngularJS in the sections below.
UI-lib Dependencies

We release a new version of our UI-lib regularly, with new features, UI controls, and bug fixes (check out our changelog to see these updates).

Make sure to update the dependencies in your project regularly.

The latest version of our UI-lib uses the following dependencies:

Using React JSX

When you add a UI control to your settings panel, add our custom properties and attributes as props so that it’s initialized correctly.

Here’s how:

  1. Declare a controller for the UI control. Each UI control has its own <UI.ctrlName>.
  2. Define the options for the UI control. Each UI control has its own properties and functions – add them as properties inside the UI control.
  3. When supported, save the value within the Wix site. For some UI controls, it’s important to save the value within the Wix site, instead of on your database. Use the wix-param property to define the style parameter key – here’s how.

Let’s use the checkbox UI control to see how it works:

Using jQuery

When you add a UI control to your settings panel, add our custom HTML properties, attributes, and functions so that it’s initialized correctly.

Here’s how:

  1. Declare a controller for the UI control. Add the name inside the wix-ctrl property.
  2. Define the options for the UI control. Each UI control has its own properties. Nest these options as an object within the wix-options property.
  3. Define the functions for the UI control. Wrap your code inside $(document).ready  and nest the functions inside a <script> tag. We have two types of functions:
    1. Event listeners, like onChange and onClick
    2. Data-management functions, like setValue and getValue
  4. When supported, save the value within the Wix site. For some UI controls, it’s important to save the value within the Wix site, instead of on your database. Use the wix-param property to define the style parameter key – here’s how.

Let’s use the checkbox UI control to see how it works:

Using AngularJS

When you create the main Angular module for the settings, add a dependency for WixControls:

When you add a UI control to your settings panel, add our custom properties, attributes, and functions so that it’s initialized correctly.

Here’s how:

  1. Declare the UI control. Controls are declared with the <wix-control> directive – and the specific UI control is declared with a name property inside the directive.
  2. Define the properties and functions for the UI control. Each UI control has its own properties and functions, defined in the props attribute (a json object defined as a string). Variables inside props are evaluated against the scope object before being passed to the UI control, so you can use variables and functions from the scope.
    Note: When using functions, don’t execute code in the HTML. Instead, point to a function that’s inside the scope.
  3. When supported, save the value within the Wix site. For some UI controls, it’s important to save the value within the Wix site, instead of on your database. Use the wix-param property to define the style parameter key – here’s how.
Note:
Our UI components don’t support Angular’s two-way binding.

Let’s use the checkbox UI control to see how it works:

How to reference other UI controls programmatically

Use the ref attribute to reference other UI controls programmatically. The ref is a string that defines the name of the variable to be added to the refs object on the scope. The ref string should be unique – otherwise the last object will overwrite previous objects.

The $scope will have a refs object with all UI controls that were defined with ref attribute. For example, when you want to change tab in the panelTabs you need to call a function on the UI control called setActiveTab().

How to handle computed properties

If you want to assign a computed string as a value in the props attribute, wrap string literals with single quotes, and wrap the entire expression with ( ).  When we read the props attribute, we run scope.$eval on this string, so all variables, functions, and filters are evaluated and the result is assigned as the value to the props object.

For example:

Wix Style Parameters

You can store certain customizations that a user changed – like your app’s color – inside the Wix site (instead of saving it on your database).

The wix-param key works with color/font parameters, numbers, and booleans.

How it works

Use our custom style parameter key, wix-param. Here’s the basic flow:

  1. Set a key name to identify this data. For example, the key name for your app’s background color can be: “backgroundColor”.
  2. Set the starting values in the UI control and in the component itself. For example, for the app’s color, you’ll save these values in the color picker and in the app’s CSS – see our example below for more guidance.
  3. For fonts and colors – we’ll reflect the user’s changes in the app. When the user changes the value, we’ll automatically change the value in the Wix site, so there’s no need for you to listen for an onChange event.
  4. For booleans and numbers, listen for the STYLE_PARAMS_CHANGE event. When the user changes the value,  we’ll automatically change the value in the Wix site. You should reflect these changes in your app.  Use the addEventListener method.
You can only use wix-param in UI controls that support it.

Supported UI controls

Color & Font Parameters

  • ColorPicker
  • ColorPickerWithOpacity
  • FontPicker
  • Font and color picker

Number Parameters

  • ToggleButton
  • RadioButton
  • Dropdown
  • Slider

Boolean Parameters

  • Checkbox
  • ToggleSwitch

Color Values

When setting colors in your app, you can use any value between color-1 to color-25 (color-1, color-2, color-3, etc). To decide the color value, use our color reference guide.

Font Values

When setting fonts in your app, you can use the values listed in the table below. To decide the font value, use our font reference guide.

Font theme you chose for your starting schemeFont Reference Number
(use in the UI control)

Font theme

(use in the site component)

Example

We’ll show you how to implement wix-param. The examples below use AngularJS, but the concepts apply to React templates/JSX and jQuery too.

Let’s use the Font & Color Picker as an example.

1. Set up the font and color picker. In your app settings panel, add the font and color picker UI control.

2. Set the same starting values in the component itself. You can use the color and font style parameters inside an internal CSS within your site component. It’s a simple template engine that uses {{value}} to interpolate the style parameters.

  1. Add the wix-style attribute in the <style> element.
  2. Separate the style key name and the fallback (default) value with a space, for example:  {{style.wix-param-key fallback_value}}.
Using AngularJS? Since AngularJS reads {{ }} as an expression, add the ng-non-bindable directive to the <style> element.

Note: You can get all the style parameters that were set in the app’s settings – use Wix.Styles.getStyleParams.

Was this page helpful?

What can we do to improve it?

What did you like about it?