Skip to main content

How to use Polipo?

The <F> component can be used to render one or more layouts from Figma, adding dynamic content and functionality.

Introduction​

The most basic usage is as follows:

<F layout="Page1/Screen1"></F>

Layer names​

Layer names in Figma are automatically normalized and converted to PascalCase, in order to be used in the code. The normalization works as follows:

  1. non-alphanumeric characters are converted to spaces,
  2. words are capitalized and joined,
  3. if the resulting name starts with a number, it is prepended by an underscore (_).

For example "1 this-is-a (very) strange layerName!!" is converted to _1ThisIsAVeryStrangeLayerName.

It is not necessary to change the names in Figma to follow this format. The normalization happens automatically and transparently.

Main layers and paths​

In order to use a Figma layer directly (a main layer), it must satisfy the following:

  1. it must be either a Figma frame or a Figma component,
  2. it must be placed directly under a page or a section (i.e., deeper layers cannot be used directly).

(Note that layers with the above properties will have their name displayed on the canvas in Figma.)

To refer to such a layer, the full path must be used, which consists of:

  1. the normalized name of the Figma page,
  2. the normalized names of the sections containing the layers, from outermost to innermost, if any, and
  3. the normalized name of the layer itself,

separated by a forward slash (/).

Examples: Page1/Frame4, Components/SimpleButton, Page1/Section2/InnerSection/Frame3.

Modifiers and selectors​

Besides a single main layer path, the layout prop can specify muliple layers and modifiers, possibly using selectors.

The syntax is inspired by Tailwind.

For example:

<F layout="sm:Screens/Desktop Screens/Mobile fill"></F>

or

<F layout="hover:Components/ButtonHover Components/Button"></F>

Modifiers​

  • fill: resizes the layer to fit the container.
  • (coming soon) show, hide,
  • (coming soon) w-fill, h-fill,
  • (coming soon) x-start, x-end, x-center, x-stretch, x-scale,
  • (coming soon) y-start, y-end, y-center, y-stretch, y-scale,
  • (coming soon) place-start, place-end, place-center, place-stretch, place-scale,
  • (coming soon) mode-VARCOLL-MODE (where VARCOLL is the name of a variable collection and MODE is the name of a mode for that collection).

Selectors​

  • hover: corresponds to CSS :hover,
  • sm, md, lg, xl, 2xl: horizontal screen size breakpoints, same as Tailwind,
  • state-NAME: applies only if the state variable NAME is truthy,
  • (coming soon) focus, focus-within, focus-visible, active, visited, target,
  • (coming soon) disabled, enabled, checked, indeterminate, default, required, valid, invalid, in-range, out-of-range, placeholder-shown, autofill, read-only,
  • (coming soon) open,
  • (coming soon) max-sm, max-md, max-lg, max-xl, max-2xl,
  • (coming soon) dark,
  • (coming soon) portrait, landscape,
  • (coming soon) motion-safe, motion-reduce, contrast-more, contrast-less,
  • (coming soon) print.

Interactivity and overrides​

To add dynamic content and interactivity, Polipo provides the following mechanisms:

  1. element props,
  2. overrides,
  3. custom children,
  4. state values.

Element props​

The <F> components accepts props that are forwarded to the main element rendered. They can be used to add attributes or event listeners.

For example:

<F layout="..." aria-role="button" onClick={/* ... */} />

Moreover, the as prop can be used to change the tag to something more specific, for example:

<F layout="..." as="button" onClick={/* ... */} />

or

<F layout="..." as="a" href="..." target="_blank" />

Overrides​

When rendering a Figma layout using <F>, it's possible to replace or modify some of its internal layers, identified by name, using overrides.

To specify overrides, pass as children a JavaScript object which maps (normalized) Figma names to JSX code.

When overriding a layer, you can use the <F> component without a layer path. In this case, it will render the element being replaced, allowing the developer to add element props.

For example:

<F layout="Page/MyForm" onSubmit={/* ... */}>
  {{
    FirstNameInput: <F as="input" name="firstName" onChange={/* ... */} />,
    LastNameInput: <F as="input" name="lastName" onChange={/* ... */} />,
    SubmitButton: <F as="button" type="submit" />,
  }}
</F>

Note that you can use any JSX code as an override, including lists, custom HTML and other React components. You can also use null to hide the overriden layer entirely. (Note that undefined will not work in this case.)

The <F> component can be used more than once inside an override, resulting in the overridden layer being shown more than once.

Overrides can be nested. In that case, new overrides will have higher priority than inherited ones.

Custom children​

Instead of overrides, you can pass an entirely new set of children which will replace the contents of the layer.

Example:

<F layout="Page1/Card">
  <F layout="Page1/Item" />
  <F layout="Page1/Item" />
  <F layout="Page1/Item" />
</F>

Using the <F> component inside the children without specifying a layer name will render the original children. This can be used to prepend or append content to a layer.

Example:

<F layout="Page1/Card">
  <div>This text will be prepended to the original children</div>
  <F />
  <div>This text will be appended to the original children</div>
</F>

You can remove all the children of a layer by passing null. (Note that undefined does not work in this case.)

Example:

<F layout="Page1/Card">{null}</F>

or

<F layout="Page1/Card" children={null} />

State values​

You can pass aritrary values to <F> which can be used to:

  • change the layer or modifiers using selectors,
  • (coming soon) change values of Figma variables,
  • (coming soon) display dynamic values inside text.

Example:

<F layout="state-even:Page/RowEven Page/RowOdd" state={{ even: i % 2 === 0 }} />