• Building your first component
  • Managing design tokens
  • Version Control
  • Using Visly components in code
  • Styling layers
  • Designing Primitives
  • Interactive components
  • Props
  • Variants
  • Composition
  • Responsive design


  • Building stateful components
  • Migrating components from code
  • Integrate Visly with Next.js
  • Building an Avatar component
  • Using slots for dynamic content
  • Using variants to customize layout
  • Stacking layers in z-index


Building your first component

Installing Visly

If you have a Visly beta invite, just download and install the Visly desktop app for macOS using the download link provided with the invite. If you want to try out Visly but haven't received an invite yet, you can request one here.

Once it's downloaded, make sure to move the app to your Applications folder. On first launch, you'll be taken through a short interactive tutorial showing you how to use the basic features of Visly. You'll learn how to start adding design tokens, how to build components, and how to use the components through code.

As part of the last step of the onboarding, the app will ask you to install the Visly command line tool. We highly recommend you install this, as without it you can't resolve merge conflicts within project files. If you didn't install this as part of the tutorial, no worries - you can also Version Control.

Creating a project

All of the design tokens and components you build in Visly are stored in a .vislyproject file. (Version Control if you're looking for more information on how to version control Visly files). The project file will be created when you choose to start a new project in Visly. We recommend you place the project file at the root of your repository, as while you can place it anywhere within your codebase, all of these docs will assume it is placed in the root. It's important that you create the project within your repository, as this file will be version controlled.

One thing you'll notice when creating a new project in Visly is that it comes with a couple of default components and design tokens. They're there as examples to learn from, so feel free to delete the ones you don't want to use.

By default, Visly places generated code in the ./src/visly folder relative to the location of your project file. This matches the number of frontend codebases that are structured. If you have your source code in a different folder (./component for example), then you can configure this within Visly by going to the Settings pages in the top right corner of the app. The code generation output location is project specific, so if you make a change, this will translate to all your team members as well, but it also means that you'll need to configure it for every Visly project.

Visly is compatible with any React project as long as your bundler supports es6 modules, css imports, and image (svg/png) imports. Currently, Visly is not compatible with React Native.

Opening an existing project

If you already have a Visly project file, you can open it by going to the File > Open project application menu. From this menu, you can also open recent projects in case you are working on multiple projects with Visly. Every project will open in its own window and you are free to have multiple windows open at the same time.

Building your first component

A great first step to get to know Visly is to build and use a simple component. Once you've gone through the initial tutorial and created a Visly project, we suggest you start by building a button and using it from code. If you'd like to test Visly outside of your main project, we suggest creating a new project based on create-react-app. Just run yarn create react-app TestingVisly and create your Visly project file inside of that folder. You can see this in the video below.

We start by creating a new primitive called MyButton. We do this by pressing the [+]button in the left sidebar next to the primitives heading. The difference between primitives and components is Designing Primitives but in short, primitives in Visly are your base interactive components such as buttons, switches, and checkboxes, while components are higher level components that don't map directly to a built-in html element such as <button> or <input>.

Once we've created our MyButton component, we'll add an icon layer to it by pressing the [+] button in the top left corner next to the layers heading. We'll also add a spacing layer the same way (Styling layers). This should result in a button component with an icon, followed by a spacer, followed by a text. You can select these layers and then, in the right hand side bar, style them however you want.

Once you're happy with the look of your component, we'll need to do one last thing before we can use it in our newly created app. Click on the icon layer and then in the right hand side bar, next to the icon heading, press the diamond shaped button. This will tell Visly that this icon should be a prop and thus controllable via code, just like any other React props you are already familiar with.

Now it's time to move over to code. To use Visly-generated components in code, you first need to install a package in your project called @visly/core. Add it through yarn or npm like so:

yarn add @visly/core

If you created a new project using create-react-app, then you'll want to open the App.ts file. The first thing we need to do is import the modules we need from Visly. We'll import these modules from the generated source code folder.

import { MyButton, icons } from './visly'

Once imported, you can use MyButton just like any other React component. If you're using TypeScript, you should even get autocompletion of props. The component we created should take two props: a text prop that's there by default for buttons, and the icon prop that we added previously. You can Managing design tokens to Visly, but for now we'll use one of the default icons available in new Visly projects.

<MyButton text="Hello Visly" icon={icons.heartFill}/>

If you run your app using yarn start (or npm start), you should see your button rendered within your newly created app. Something you can test out now that your dev server is running is to make a change to your component in Visly (change the text size for example) and see how that is instantly reflected in your running application. Visly works with all existing hot-reload implementations, just like when you build components with code.