Speed your workflow with the reusable power of components.
A component is an object or group of objects that can be reused multiple times across files. This can help you maintain consistency across a group of designs.
-A component has two parts:
+A component consists of two elements:
All component copies used in a file are linked in a way that updates made to the Main component can reflect in their component copies. You can override properties for component copies, so that you can manage singularities while maintaining properties in common.
-You can duplicate a component the same way you can duplicate any other layer. When duplicating a component, you are creating a component copy that will be linked to its main component.
-You can duplicate a component as a new main component from the assets sidebar. Just select the component at the library, open the menu with right click and select the option "Duplicate main".
You can delete main components and its copies anytime the same way you can delete any other layer.
Deleting a main component at the viewport means deleting it at the assets library and viceversa, so be careful!
If a main component has been deleted and you have access to a copy of it, you can use the copy to restore its main. There are two ways to do it:
Where's my component? There are ways to find main components at the assets panel and at the design viewport.
+ +Select a main component at the viewport and then press "Show in assets panel" at the options of the right sidebar.
+Select a component copy and then press "Show main component" at the viewport menu or the right sidebar menu.
+If you find a page at a file called "Main components" this will probably mean that the file had assets with the previous components system and has been migrated to the current components system. The previous system didn't have the components as layers at the design file, only at the assets library, so when migrating a file to the new version Penpot automatically creates a page where to place all the components, grouping them using the library groups structure.
+
+At the Components section from the Assets library, there are two ways to create groups in a components library.
You can ungroup the components the same ways you can group them, via the menu option ("Ungroup" in this case) or renaming them.
-One very direct way to move components between groups at the assets library is by dragging them.
Where's my component? There are ways to find some components at the assets panel and at the design viewport.
+Detach a component copy to unlink it from its Main component and transform it into a group layer. Press Ctrl + Shift + K or right click and select the option “Detach instance” at the component menu.
+You can also detach components in bulk by selecting several components and performing the same action.
-Select a main component at the viewport and then press "Show in assets panel" at the options of the right sidebar.
+You can add text annotations to main components. The annotations are shown in every component copy. It is extremely useful to attach specifications that can be read at each component copy.
Select a component copy and then press "Show main component" at the viewport menu or the right sidebar menu.
+The annotations are also shown at the Inspect tab, as another option to improve communication between designers and developers.
Main components represent the more generic information of an element in a design system. You will usually need to change specific things (like a text, a color or an icon) in a component while maintaining the inheritance of the rest of it properties. Component overrides allows you to do that in Penpot.
+Overrides are modifications made in a specific copy that are not in its main component. With overrides you can keep changes at the component copies while maintaining synchronization with the Main component.
+
+Right click and select the option “Reset overrides” at the component menu to get it to the state of the Main component.
+You can push changes made at a component copy to a main component:
-Main components represent the more generic information of an element in a design system. You will usually need to change specific things (like a text, a color or an icon) in a component while maintaining the inheritance of the rest of it properties. Component overrides allows you to do that in Penpot.
-Overrides are modifications made in a specific copy that are not in its main component. With overrides you can keep changes at the component copies while maintaining synchronization with the Main component.
-
-Right click and select the option “Reset overrides” at the component menu to get it to the state of the Main component.
-Detach a component copy to unlink it from its Main component and transform it into a group layer. Press Ctrl + Shift + K or right click and select the option “Detach instance” at the component menu.
-You can also detach components in bulk by selecting several components and performing the same action.
- - -Penpot allows you to easily substitute component copies with other component copies.
You can add text annotations to main components. The annotations are shown in every component copy. It is extremely useful to attach specifications that can be read at each component copy.
+ +Variants allow you to group similar components, such as buttons, icons, or toggles, into a single, customizable component. Rather than navigating through separate components for every possible state, size, or style, you can manage them all from one unified component using clearly defined properties.
+Imagine a single button component that can switch between primary and secondary styles, active and disabled states, and small to large sizes. Useful, right? That’s the power of Variants.
+ +The annotations are also shown at the Inspect tab, as another option to improve communication between designers and developers.
+A component’s variants are organized by properties and their values.
+Each variant is simply one unique combination of values across all properties (for example, Color=Primary + Size=Small + State=Hover).
Variants must have at least one property, and property values should be kept consistent to make switching predictable and to preserve overrides across connected layers.
+ +You can create variants from an existing component or from another variant:
+
+ 
+When a variant is created:
+
If you find a page at a file called "Main components" this will probably mean that the file had assets with the previous components system and has been migrated to the current components system. The previous system didn't have the components as layers at the design file, only at the assets library, so when migrating a file to the new version Penpot automatically creates a page where to place all the components, grouping them using the library groups structure.
+Properties are key to defining and differentiating your variants. They appear in the Design tab when a variant or component with variants is selected.
+ 
[property_name]=[value].[property_name]=[value].
+Variants must have at least one property. You can’t delete the last one.
+When multiple variants are selected, the Design tab will show all their properties and values. If a property has different values across the selected variants, it will display “Mixed,” allowing you to override them collectively.
+ +If you delete the last variant, the entire component is removed.
+ +If you have a copy of a variant whose original was deleted, you can restore it:
+Once you have created your variants, you can place a copy of a component with variants into your design and then switch between its different versions.
+ +Drag and drop a component with variants from the Assets tab onto the design viewport, just like you would with any other component. Once placed, you can then use its properties in the Design tab to switch to the desired variant.
+ +When a variant is selected:
+
+A key benefit of variants is the ability to preserve overrides when you switch between them. An override is a specific change you make to a component instance that diverges from its original definition (e.g., changing text content or a specific color).
+Layers between variants are considered connected if they:
+
+Example: If Variant 1 has a text layer named label with red color, and you change its content to Click here in an instance, then switch to Variant 2 (which also has a label text layer), the Click here content will be preserved, and Variant 2’s color will be applied.
Changing any of these (e.g., renaming or grouping a layer) breaks the connection, but reverting the change will restore it.
+ +If you already have multiple related components, you can combine them into a single component with variants:
+
+Conditions:
+When combined:
+To turn a variant into an independent component:
+The new component’s name includes the original component name and the variant’s property values.
\ No newline at end of file diff --git a/docs/user-guide/introduction/shortcuts.njk b/docs/user-guide/introduction/shortcuts.njk index 00fdadf777..0f9a317bdd 100644 --- a/docs/user-guide/introduction/shortcuts.njk +++ b/docs/user-guide/introduction/shortcuts.njk @@ -263,6 +263,11 @@ desc: Get quickstart tips, shortcuts, and tutorials for Penpot! Learn interface