@blackpixel/framer-carouselcomponent
v1.0.1
Published
Generate a scrolling carousel of items in a variety of configurations.
Downloads
8
Readme
CarouselComponent Framer Module
The CarouselComponent module allows you to generate a scrolling carousel of items in a variety of configurations.
Installation
NPM Installation
$ cd /your/framer/project
$ npm i @blackpixel/framer-carouselcomponent
Manual installation
Copy or save the CarouselComponent
file into your project's modules
folder.
Adding It to Your Project
In your Framer project, add the following:
ControlPanelLayer = require "CarouselComponent"
API
new CarouselComponent
Instantiates a new instance of CarouselComponent.
Available options
myCarousel = new CarouselComponent
# Item cells
itemCount: <number>
rounded: <boolean>
itemMargin: <number>
itemBorderRadius: <number>
itemWidth: <number>
itemHeight: <number>
smallItemWidth: <number>
smallItemHeight: <number>
# Labels
title: <string>
link: <string>
captions: <array of strings>
subcaptions: <array of strings>
# Layout
margins: <array of numbers> ([topMargin, rightMargin, bottomMargin, leftMargin])
wrap: <boolean>
sideCaptions: <boolean>
topAlignSideCaptions: <boolean>
# Hero-specific controls
heroCaptionAlign: <string> ("left" | "center" | "right")
centerheroItem: <boolean>
sideHeroCaption: <boolean>
topAlignHeroCaption: <boolean>
# Colors
boxColor: <string> (hex or rgba)
iconColor: <string> (hex or rgba)
titleColor: <string> (hex or rgba)
linkColor: <string> (hex or rgba)
captionColor: <string> (hex or rgba)
subcaptionColor: <string> (hex or rgba)
# Typography
fontFamily: <string>
titleFontSize: <number>
titleFontWeight: <number>
titleMargin: <number>
linkFontSize: <number>
linkFontWeight: <number>
captionFontSize: <number>
captionFontWeight: <number>
captionMargin: <number>
captionMaxHeight: <number>
subcaptionFontSize: <number>
subcaptionFontWeight: <number>
subcaptionMargin: <number>
subcaptionMaxHeight: <number>
titleAlign: <string> ("left" | "center" | "right")
captionAlign: <string> ("left" | "center" | "right")
# Icons
icons: <boolean>
iconBorderRadius: <number>
iconSize: <number>
iconMargin: <number>
# Image assets
imagePrefix: <string> ("images" directory assumed)
imageSuffix: <string>
iconPrefix: <string> ("images" directory assumed)
iconSuffix: <string>
# Actions
itemActions: <array of actions>
linkAction: <action>
# View CarouselComponent frame
debug: <boolean>
# Other
forceScrolling: <boolean>
Using side captions
Specify sideCaptions: true
to vertically align captions alongside cells, rather than underneath. Specify topAlignSideCaptions: true
to align side captions to the tops of their adjacent cells.
Using the wrap feature
If you specify wrap: true
, the first item in the carousel will display on its own row as a hero item. This item can be controlled independently of the rest of the carousel. Secondary cells will be sized according to smallItemWidth
and smallItemHeight
, rather than itemWidth
and itemHeight
.
Text alignment
You may specify "left"
, "center"
, or "right"
for both titleAlign
and captionAlign
. heroCaptionAlign
is also available when using the wrap
feature.
Using icons
Icons can be displayed under each item's cell. Specify icons: true
to enable this. Enabling icons prevents the use of side captions.
Using images
All images are assumed to live in the images directory and be numbered starting with zero. You may supply a prefix and suffix. If your item images are located in an items
directory within images
and named:
cell0.png
cell1.png
cell2.png
then your imagePrefix
will be "items/cell"
and your suffix would be "png"
.
Icon assets work the same way.
Do not include the images
directory in imagePrefix
or iconPrefix
.
Assigning margins
Margins are supplied in the same order as they are for CSS. margins: [40, 10, 15, 5]
will provide a top margin of 40, a right margin of 10, a bottom margin of 15, and a left margin of 5. The first item is positioned according to the top margin; however the title and link are positioned relative to the first item using titleMargin
.
Maximum caption heights
You may enforce text truncation by supplying captionMaxHeight
and subcaptionMaxHeight
. The threshold that triggers truncation will depend on font size.
Scrolling
The CarouselComponent will attempt to provide scrolling only when its content extends beyond the visible area. To enforce scrolling regardless, specify forceScrolling: true
.
Assigning actions
The link button in the upper right of the carousel can be given an action, as can individual item cells. The link will only appear if you supply a string with link: <string>
and the CarouselComponent includes at least two items. Item actions should be arranged in a comma-separated array, one action per line.
linkAction: -> print "link"
itemActions: [
-> print "1",
-> print "second",
-> print "item the third"
]
Referring to parts of the CarouselComponent
The CarouselComponent
contains a PageComponent that can be accessed with row
. Items and their components can be accessed with the items
array. heroItem
is available when wrap is set to true.
print myCarousel.row.currentPage
print myCarousel.heroItem?.caption?.text
print myCarousel.items[0].textBlock
print myCarousel.items[0].cell
Known issues
CarouselComponent
does not calculate its full height until it has finished populating its content. Don’t attempt y: Align.center
. Instead, use myCarousel.y = Align.center
following instantiation.
Website: blackpixel.com · GitHub: @bpxl-labs · Twitter: @blackpixel · Medium: @bpxl-craft