Create custom sections for Symbols

Symbol Browser arranges all of your Sketch Library symbols based on their names and arranges them in sections. But sometimes that might not be the desired grouping. In such cases, you can define your custom sections and assign symbols to these created sections.

Before we jump into the "how" let's take a moment to understand the core layout of the Symbol Browser.

Understanding Symbol Browser layout

The below image shows core sections and how they appear in the "Symbol Browser".

Every Symbol has to be part of a Sub Section.

Steps to create custom Symbol sections

You can check out the Example Sketch library to see possible ways to create sections or follow the instructions below:

1. Define Parent section

Below is code to define Parent section

!StickerSection @Section
title: Parent Section
description: 'A description'

Refer Metadata table for allowed values.

2. Define Sub-section

Below is code to define sub section under "Section" parent ssection

!StickerSection @Section.SubSection
title: Sub Section Title
description: 'A description'

Refer Metadata table for allowed values.

3. Tag Symbols to custom Section

To add any Symbol to the custom section, we need to append the Symbol name with the sub-section ID. Sub-section ID from the above example would be @Section.SubSection.

To add a Symbol with name Button / Solid / Active to this section it should be renamed to Button / Solid / Active @Section.SubSection

You can also tag Artboards, Groups, Layers and even Symbol Instances. See the below image:

4. Change (Sub)section layout

Be default all sub-sections appear as columns (like Subsection 2 and 3). You can also opt for making sub-section as a row (like Subsection 1). Sample code to define section with such layout would be:

!StickerSection @Section
title: Parent Section
description: 'Parent section description'

!StickerSection @Section.SubSection1
title: Sub Section 1
layout: 'row'

!StickerSection @Section.SubSection2
title: Sub Section 2

!StickerSection @Section.SubSection3
title: Sub Section 3

Syntax of text-layer metadata

Sample metadata:

#Sample code for a Parent section

!StickerSection @Section
title: Parent Section
description: 'Note that this description supports basic HTML tags:<br/><b>This is Bold</b>'
links:
- title: Dummy Link
  url: http://pratikshah.website

#Sample code for a Sub section

!StickerSection @Section.SubSection
title: Sub Section
description: 'Provides description for the Sub-section'
backgroundEach: '#fafafa'
layout: 'row'

Below are the currently supported section properties (keys):

Property	Type		Description
title	string	optional	The title of the section. If not provided uses sectionId as a title.
sectionId	string	required	Section IDs look like @Section1 or @Section1.SubSection. Note that section IDs can only have letters and numbers, so avoid any special characters like semicolons, spaces, ampersands, etc.
description	string	optional	A longer description of the section and/or sub-section.
background	string	optional	Allows you to add background color to entire sub-section. Takes hex code color values like #ffffff.
backgroundEach	string	optional	Like background, but sets a background color to each Symbol / Sticker.
hideNames	boolean	optional	Default false. If true, hides symbol/sticker names and will show only image preview.
links	array	optional	An array of links to show below the section description, where each link is an object with a title and url. Only works for Parent sections (e.g. @Section).
layout	string	optional	An optional layout type for sub-sections. Allowed values are flow and row. Default layout value for sub-section is flow which arranges symbols in a column/vertically stacked fashion.