Site Components

Overview

Now that you’ve planned your app’s components, you’re ready to start designing your app. We’ll go over a few general guidelines to follow in your site component, so that your app feels native to the Wix platform.

Before we dive in, we’ll first give you a general orientation of how users will add and use your app.  Knowing this basic user flow will help you design an app that integrates seamlessly with our platform.

User Flow

Site Apps

Here’s the basic flow of how users add site apps, or site components that are part of a multicomponent app. (You can learn more about the user flow for multicomponent apps, below.)

The best way to learn is to try it yourself, so we recommend adding a site app to your Wix site – for example, the Events app.

1. Users can browse the App Market and add your app. When users add your app, it opens in the editor.

2. Users open the App Settings panel to set up and customize your app.

3. Once the site is published, site visitors can see and interact with the app.

Multicomponent Apps

When users add a site component that’s part of a multicomponent app, the basic flow is a little different.

The best way to learn is to try it yourself, so we recommend adding a multicomponent app to your Wix site. Try one of the examples below.

Here’s how it works for different types of multicomponent apps:  

  • Apps with a few site components – When users add your app, only the default and essential site components are added automatically (you’ll define this in the Dev Center). Users can add the other site components from your app’s settings panel.  
  • Apps with a site component and a dashboard component – Users can add your app from the editor or the dashboard (for example, see the Wix Bookings app):
    • When users add your app from the editor, the site component opens. However, the dashboard component is added as well, and users will see it next time they go to their dashboard.
    • When users add your app from the dashboard, the dashboard component is added right away, and they’ll see a notification telling them to add your site component.
Iframe Size

Widgets

  • Decide on an initial size. We recommend making the widget small, with a max height of 650px (since the most common screen resolution is 1366×768). You’ll set the initial width and height in the Dev Center.
  • Adjust the iframe’s height dynamically. Go according to the app’s content (use the setHeight SDK method). Don’t add scroll bars.
  • Make your app responsive and optimize for mobile. Make sure your app looks great at any size, and on any device. Learn more.
  • (Optional) You can make your app full-width. If your app is fully responsive, you can allow users to extend your app to the full width of the browser window – or you can make the app full width by default. Here’s how.

Fixed-position Widgets

  • Decide on an initial size. We recommend making the widget small, with a max height of 650px (since the most common screen resolution is 1366×768). You’ll set the width and height in the Dev Center.  Note that users can’t resize fixed-position widgets in the editor.
  • (Optional) Expand your app when site visitors use it. You can resize the widget when site visitors interact with it – like a chat window that’s usually minimized, but “pops out” when a site visitor clicks on it. 

Pages

  • Keep the default width in mind – The default width of the page component is 980px, just like every other page in the site.
  • Adjust the iframe’s height dynamically – go according to the app’s content (use the setHeight SDK method). Don’t add scroll bars.
  • Make your app responsive and optimize for mobile. Make sure your app looks great at any size, and on any device. Learn more.
  • (Optional) You can make your app full-width. If your app is fully responsive, you can allow users to extend your app to the full width of the browser window – or you can make the app full width by default. Here’s how.
Demo Data

When users first add your app, show demo data so that they can quickly get a sense of what your app does.

Let’s use the Yelp app as an example – when users add this app app, they can see right away how it’ll look on their site:

App Setup

Create an App Settings panel to guide users in setting up your site component. This panel is very important, because the user experience and options you offer here could determine whether users choose your app.

The entire implementation of the settings panel – both design and development – is done using our UI-lib. Our UI-lib includes both a template for the panel structure and also the UI controls you’ll use in the panel.

We explain exactly how to design your App Settings panel in this guide.

Popups/Modals

If you need to open a window or dialog box in your app:

  • Use the Wix popup or modal. We’ll explain the differences below so you can choose which one is better for your app.
  • Keep site visitors within the Wix platform. Don’t open windows in a new tab or use browser-native popups such as window.alert(), window.prompt(), and window.confirm().
  • The max height is 650px. Don’t exceed this size for your popup/modal.  

Wix Popup

The Wix popup is a window that opens over the user’s Wix site (live or preview). Site visitors can close it by clicking the close button, and you can close it within the app. Use the Wix.openPopup SDK method.

Here’s an example of a Wix popup:

Have your own popup style? You can open our popup in a “bare style” – without a border, shadow, or close button – and put your own instead.

Wix Modal

The Wix modal is a lightbox-style window that opens over the Wix site. Site visitors can close it by clicking the close button or anywhere outside of the lightbox, and you can close it within the app.  Use the Wix.openModal SDK method.

Here’s an example of a Wix modal:

Alerts/Notifications

Does your app notify site visitors about an update, like a success message or input error? Show the alert visually, and don’t rely on sound or color alone to signal a change.

This is an important part of making your app accessible to people with vision or other impairments – someone who is color blind may not notice a color change.

Here’s an example of the right and wrong way to show an error:

Preview

As Wix users edit their site in the Wix Editor, they can switch from “editing mode” to “preview mode” to see what their live site will look like. Make sure your app looks the same in “preview mode” as it does in the live site.

You can detect when the user is in preview mode – listen for the EDIT_MODE_CHANGE event in the addEventListener method. Then just display your app the same way you do in the live site.

Responsive

Make sure your app looks great at any size, and on any device. When the size of the iframe or device changes, adjust the layout and design to best fit the new size.

You’ll set the initial width and height of your app in the Dev Center. Adjust the layout and design dynamically:

  • As the user resizes your app in the Wix Editor
  • According to the site visitor’s device (mobile or desktop)  
Note:
The info below isn’t relevant to fixed-position widgets, since users can’t resize these components in the Editor. Learn more about how to optimize fixed-position widgets for mobile.

How to make your app responsive:

Your app must look good and work well in at least 3 sizes – small, medium, and large screens. Here’s what we suggest:

  1. Design for mobile first, then think about bigger screens. We recommend using a grid-view to prepare your app’s layout for the following sizes:  
    • 320px and less – follow our mobile design guidelines
    • Between 321 and 550px
    • Between 550 and 980px
  2. Adjust the layout dynamically, as the iframe size or device changes. Resize images, content, and sidebars to fit the new dimensions. We recommend using media queries to display the best layout for the current width.  
    Note: Not using media queries? You must have a dedicated mobile endpoint
  3. Optimize your app for mobile. Check the device type using our SDK, and make sure the app works well on mobile (e.g., by supporting swiping and tapping actions). Learn more about mobile design.
  4. (Optional) You can decide on a minimum height and width for your app. If the user makes the app smaller, you can snap the component back to the minimum size (use the resizeComponent SDK method).
Important:
When adjusting your app, change the app’s layout only – the functionality must be the same in all sizes. If your app has a feature that’s only relevant for desktop or mobile, discuss it with your account manager.

Example of a responsive app

This is how the app looks when it’s added to the site:

If the user increases the iframe width, the height changes and the layout is adjusted accordingly (also note that there is now more white space).

When the user decreases the iframe width, the height automatically changes and the content is adjusted accordingly.

You can see that the functionality of the app remained the same, even when shrinking the app to its minimum size.

Mobile Design

Optimize your app for mobile devices. A great mobile experience is important to Wix users, because many site visitors browse on a mobile device.

How to design your app’s mobile layout:

1. Limit the width of the app to 320px, and the content to 280px. This leaves enough white space so that the mobile view looks clean and clutter-free.

2. Keep it short. If there’s a lot of data, you can provide a link, add pagination, or allow visitors to expand/collapse. If needed, you can adjust the app’s height by pushing other components further down the page (use the setHeight SDK method and set overflow to false).

3. Make your text readable. Use the following font sizes:

  • Page title (for page apps only): 34-30px
  • Heading: 24-30px, depending on the hierarchy
  • Main title: 20px
  • Subtitle: 16-18px
  • Paragraph: 14-16px
  • Button text: 16px

4. Make your buttons the right size. Buttons should be at least 80px wide, and the height should be between 36-42px.

5. Leave enough space between elements. Follow these guidelines:

  • Add at least 20px between two elements, for example: between text and and image, between buttons, between button and text, etc.
  • Add space between two lines of text:
    • 1.4 em for running text
    • 1.2 em for titles

Here’s a style guide to help you follow the guidelines above:

6. Make important elements easily clickable. Use single-tap buttons or horizontal bars. For example, the most important action in our Events app is to register for an event, so we made it really easy for visitors to do:

7. Support common mobile actions. Meet user expectations by supporting these actions:

  • Tap – Allow site visitors to tap on all interactive elements, like buttons and links.
  • Swipe – Allow site visitors to swipe right/left in slideshows and similar elements.

Example

Add our Events app to your website, and switch to mobile view in the editor to see an example of an optimized mobile app. Note that while the layout of the app is different between the two views, the functionality is the same.

Check out the images below and compare the desktop and mobile views.

Desktop view:

Mobile view:

Full Width

If your widget/page component is fully responsive – meaning that it looks good in a wide range of different sizes that the user might choose – then you can allow users to extend your app to the full width of the browser window.

If it makes sense for your app, you can also make your app full width by default.

How to give users the option to make your app full-width:

Your app will be added with the default dimensions you set in the Dev Center, but you can allow users to extend your app to the full width of the browser. There are two ways to do this, and it depends on the layouts you’re offering for your app in the App Settings panel:

  • If all of your layouts are fully responsive: The Wix Editor already has the full-width option, so users can extend your app directly from the Editor. All you need to do is let us know that your app is fully responsive:
    1. Go to your app’s page in the Dev Center. In the Register Your App tab, in the App Components area, click Edit next to your widget.
    2. In the Widget Endpoint Content section, check Endpoint is fully responsive.
  • If only some of your layouts are fully responsive: You can offer an option in your App Settings panel that allows users to extend the widget to full width – just make sure to only show this option if the user chose one of the responsive layouts!
    Use the setFullWidth SDK method.

How to make your app full width by default:

You can also make your app full width by default, so that it’s already  stretched to the full width of the browser when the user adds your app. Here’s how:

  1. When editing your app component in the Register Your App tab, go to the Widget Endpoint Content section and check Endpoint should be full width by default.
  2. Make sure that your app’s default layout is fully responsive and looks good in full width. If the user changes the layout to one that isn’t fully responsive, you should change the app size to the default dimensions you set in the Dev Center.
Color

Integrate with the site’s colors

We have a collection of different color palettes that users can choose for their site. Each color palette is a set of colors that work well together, for example:

Choose your app’s colors dynamically, according to the site’s color palette. This way, your app integrates seamlessly and looks great right away – which means less work for the user.

Here’s a quick look at what you’ll need to do:

  1. Create the initial color scheme for your app. We have a template for our color palette, and we’ll explain how it works below. Use this template to create your app’s initial color scheme.
  2. Allow users to change the app’s colors. In the App Settings panel, add a color picker for each element in your app.

Now, we’ll walk you through our color palette and explain how to choose your app’s color scheme.

During development, you’ll need to set the initial color scheme in two places – in the color picker and in the app itself.

Get to know our color palette template

Not only do you want your app to integrate with the site’s color palette – but it’s also important that all of the colors used in your app look good together. For example – the text should always be readable against the background, the main action should stand out, etc.

To make this easy for you, we created a template that’s based on the two left columns of the color palette.

Use this template to create your app’s color scheme. Here’s how it works:

1. Understand the palette structure.

    • Each number represents a color. The actual color will depend on the specific color palette used in the site. For example: color-8 in the palette above has a purple hue, but can be blue in a different palette.
    • The first column is grayscale.
    • The second column is a range of tints for the “brand color”. The color varies, depending on the color palette.

2. Assign a number to each element in your app. Follow our color reference guide to create your color scheme. You can use the same color for a few different elements – we call this the “master color”.  Here’s a quick preview:

(We don’t recommend using a third color – but if needed, you can use the third column.)

Tip: Add any app (for example, the Events app) to your Wix site, and then change your site’s color palette so that you can see how the app changes according to different color palettes.

Here’s an example to show you how it works. You can see the app’s color scheme and how it looks with the color palette shown:

Color Reference Guide

Use this table as a guide to choose a “color” for each element in your app.

Important:
Stick to the color values that we list below. We specifically chose these values so that the colors in your app will work well together and there will be enough contrast.
ElementValue
Font

Integrate with site’s fonts

Users can customize the font for any text in their site. They can also create font themes for different types of text, like titles, running text, etc.

Each font theme is a set of properties that define what the text should look like – size, font family, etc. For example, a user might decide that all titles in the site should be bold, size 20, and Helvetica.

Choose your app’s font dynamically, according to the site’s font themes. This way, your app integrates seamlessly and looks great right away – which means less work for the user.  For example, your app’s heading should look like other headings in the user’s site.

Here’s a quick look at what you’ll need to do:

  1. Create the initial font scheme for your app. First understand how our font themes work, and then decide your app’s initial font scheme.
  2. Allow users to change the app’s font. When you create the App Settings panel, add our font picker. 
During development, you’ll need to set the initial font scheme in two places – in the font picker and in the app itself.

Decide on an initial font scheme

When users add your app, we’ll use your initial font scheme to update the app’s font according to the site’s font theme for this type of text (i.e, heading, running text, etc).  

Follow these guidelines to choose the initial font themes you want to use in your app:

  • Know what works. We suggest using these font themes, because we know that they’ll look great in our templates:
    • Use Paragraph 2 (medium body text) for running text and button text, since it’s the most readable and popular theme used in our sites. You can use it for subtitles too – just customize the size to make it bigger than the running text.
    • Use Heading 5 for the title or heading of your widget/fixed-position widget.
    • Page components only: Use Heading 2 for the page title.

We don’t recommend using the other font themes that are available in Wix.

  • Less is more. Use up to 3 different font themes in your app, like Paragraph 2 for running text and button text, and Heading 5 for a title.
Tip: Add any app (for example FAQ) to your Wix site, and then change an element’s font theme so that you can see how the app changes according to different themes. It’ll help you choose the right font scheme for your app.

Here’s an example of how an app integrates with the font themes in a specific site:

Accessibility

Apps on the user’s live site must be accessible, so that all site visitors can use your app – including those with disabilities.

Accessibility is easy to implement, and along the way you’ll end up fixing issues that will improve the experience for all site visitors.

Even though you’ll do most of the accessibility work during development, you should start planning for it in the design stage. 

Keep these points in mind as you design your app:

  • When possible, use HTML elements instead of designing your own. HTML elements are already accessible, so there will be very little work for you to do later.
  • Know the right way to show updates or errors in your app. Check out our example for the right and wrong way to do alerts/notifications.
  • Make sure your app has a visual focus indicator for keyboard users. Browsers already have a focus indicator to show site visitors where they are in the site. 
  • Can users upload images, video, or audio files in your app? Plan how screen-reader users will experience this content on the site.  For example, if an image doesn’t have a description, then a screen reader can’t describe it to the user. When you design your App Settings panel or Dashboard component, allow users to add information about their content: an  alt-text attribute for images, a transcript for audio files, captions for videos, etc.

Was this page helpful?

What can we do to improve it?

What did you like about it?