Documentation

  • Getting Started
  • Using Visly from code
  • Version Control
  • Tokens
  • Layers
  • Primitives
  • Interaction States
  • Variants
  • Props & Slots
  • Composition & Inner Components
  • Built-ins
  • Responsive Design

Tutorials

  • Using Visly with Create React App
  • Using Visly with Next.js
  • Using Visly with Gatsby
  • Creating stateful components
  • Routing with Visly
  • Using variants for responsive design
  • Create dynamic UI with inner components
  • Reuse existing components with Slots

Documentation

Using Visly from code

To get started using components and tokens you've created in Visly from code, you first need to make sure you have a React project, either an existing project or a freshly created one. You'll want to start by creating or moving your *.visly file into the root of this React project.

The next step is to install Visly's runtime dependencies. This mostly consists of a few helper functions that will be used by Visly-generated code to handle accessibility.

npm install @visly/core

Output location

Visly will by default place all generated code within src/visly, relative to the location of your *.visly file. For example, if your project is located in ~/projects/my-app/components.visly then the generated code will by default be places in ~/projects/my-app/src/visly. You can configure where you want code to be generated in the Visly settings page.

NextJS

If you are using Next.js, you'll need to add some additional configuration to make sure everything works as expected. The first thing you'll need to do is enter the settings screen in Visly and enable Next.js compatibility by ticking the relevant checkbox.

The next step is to add a next.config.js file in the root of your project and add the next-images plugin. You'll also need to install the plugin using npm install next-images.

const withImages = require('next-images');
module.exports = withImages();

Finally, if you don't already have a pages/_app.js file create one and import the Visly global css file. This file includes all the CSS needed to render your components. Make sure the import path matches the location at which you configured Visly to place the generated code. Read more about custom app components here.

import '../visly/styles.css'

function MyApp({ Component, pageProps }) {
  return <Component {...pageProps} />
}

export default MyApp

Tokens

While you'll generally be using Tokens directly in Visly, there are also situations where you'll want to reference a token defined in Visly from your code. These tokens are exported in a way that makes them easy to use together with style objects passed to React components. Tokens are imported as the following:

  • Colors are imported from ../visly/colors and exported as rgba() strings;
  • Icons are imported from ../visly/icons and get served as remote files. This requires bundler support, but the vast majority of bundlers have this pre-configured;
  • Text styles are imported from ../visly/textstyles and are exported as objects with properties that match CSSProperties accepted by the React style prop;
  • Sizes are imported from ../visly/sizes and exported as a css dimension string, for example "24px"; and
  • Shadows are imported from ../visly/shadows and exported as a css box-shadow string, for example "0px 2px 4px 0px rgba(0,0,0,0.2)".

It's important to update the import paths so they match the location from which you have configured Visly to generate your code. For example, if you configured your code to be generated in a src/ui folder, your code may look something like this:

import { h1 } from '../ui/visly/textstyles'

<span style={h1} />

Components

Visly components are imported just like tokens. However, by default, components are exported from the root visly folder.

import { MyComponent } from '../visly'

<MyComponent />

Components built in Visly work exactly like components you built previously with code - after all, they are just React components. To learn more about the specific API and props of specific components you built in Visly, we recommend you have a look over the Primitives.

Component references

Component references are covered in much more details over Composition & Inner Components. In brief, when a component contains a component reference, its props can be configured in Visly. However, they can also be configured additionally through code. This is especially useful for adding event listeners. For example:

import { MyComponent } from '../visly'

<MyComponent Button={<MyComponent.Button onClick={onSubmit} />} />

Inner Components

Inner components are covered in much more details over Composition & Inner Components. In short, importing an inner component is as simple as importing the main component and then accessing the inner components as properties on the root component. For example:

import { MyComponent } from '../visly'

<MyComponent InnerComponent={<MyComponent.InnerComponent />} />

Folders

Much like creating components using code, Visly gives you the ability to organize your project into folders.

There folders are also represented in the generated code.

import { MyComponent } from '../visly/FeatureX'

<MyComponent />

Overriding styles

While we expect you to perform the vast majority of styling from within Visly, it's sometimes necessary to add additional styles from code. This is especially important when arranging Visly components within a layout together with non-Visly components. For example, you may want to add some margin to a Visly component or center it within its parent. All Visly components accept a style prop for this use case.

import { MyComponent } from '../visly'

<MyComponent style={{ margin: 10, alignSelf: 'center' }}/>

This also works together with css-in-js libraries such as styled-components.

import styled from 'styled-components'
import { MyComponent } from '../visly'

const StyledComponent = styled(MyComponent)`
  margin: 10px;
  align-self: center;
`

<StyledComponent />

Workflow

Visly is built to allow you to build UI components visually while also coding on business logic in VSCode (or whatever editor you choose to use). The recommended workflow is to have both your code editor and Visly open at the same time while you have a dev server running in the background. As you make UI changes in Visly and business logic changes in code, your web app should automatically refresh as long as you have hot-reload set up.

Once you're happy with the feature you have built, or bug you have fixed, you'll move on to creating a commit and pull request for it. This pull request will contain both the changes to business logic in your Javascript files, as well as your UI changes and generated code from Visly. Version Control