# Fold UI complete reference # Fold Core > Component-oriented documentation for `@fold-ui/core`, generated from the existing Storybook stories, React prop metadata, and component CSS. - Version: `0.25.1` - React peer dependency: `>=18.3.0` - Source: [github.com/fold-ui/fold](https://github.com/fold-ui/fold) ## Installation and setup ```bash npm install @fold-ui/core ``` ```tsx import { AppProvider } from '@fold-ui/core' import '@fold-ui/core/dist/styles.css' export function App() { return {/* application */} } ``` Import public APIs from the package root. Use documented props and CSS variables instead of guessing names or importing internal source paths. ## Component index - Accordion: The accordion component is a list of vertically or horizontally stacked headings that collapse or expand associated content. - Affix: The affix component acts as a positioning container that allows an element to behave as if it were relatively positioned until it reaches a specified scroll position, at which point it becomes fixed. - Alert: An alert component is an element that displays a brief, important message in a way that attracts the user's attention without interrupting the user's task. - Aspect Ratio: Aspect Ratio is used to fix the dimensions of a container to a specified aspect ratio based on the width or height. - Attachment: The Attachment component displays a file attachment that has been uploaded by a user or the system. - Audio: The Audio component is used to embed sound content in websites & applications. - Avatar: The Avatar component serves as a representation of the user, showcasing their profile picture, initials or any child content. - Badge: The Badge serves as a small label or indicator for UI elements. - Bar Chart: The BarChart component compares values across categories, grouped by series. - Breadcrumb: The Breadcrumb component lists a series of links that provide a visual representation of a page's position within a website's hierarchical structure. - Button: The Button component enables users to perform actions, make selections, and submit forms. - Card: The Card component envelops content within a styled container to ensure a consistent visual style within a design system. - Carousel: The Carousel component is a slideshow that cycles through various elements, including images, videos, and text. - Checkbox: The Checkbox component is an input element, allowing the user to select single values for submission in a form - Collapsible: The Collapsible component toggles the visibility of its content depending on a boolean property. - Color: The Color Palette and Color Picker components present the user with a set of input options for color values. - Cookie: The Cookie component displays a modal window to provide the user with the option to either accept or decline the cookie policy. - Copy: Using the Copy component, users can easily duplicate text values to their clipboard. - Cropper: The Cropper component enables users to manipulate image files by cropping, rotating, and zooming. - CSV Importer: Make sense of imported data by correctly mapping columns with the CSV Importer. - Data Grid: A robust & flexible Data Grid component engineered to handle diverse datasets with ease. - Date & Time Pickers: Date Time components offer highly versatile options for displaying and inputting dates. - Dialog: The Dailog component is a modal window that prompts the user for information or some form of action. - Divider: The Divider component creates a division between content using either a horizontal or vertical line. - Drag: The Drag component is a flexible drag-and-drop element that supports a wide range of applications. - Drawer: The Drawer component displays a Modal attached to one edge of the screen. - Editable: The Editable component enables users to edit simple text content inline. - Form: The Form component provides quick access to native (HTML) form elements. - Grid: The Grid component wraps "display: grid", arranging child elements within a grid structure comprised of rows and columns. - Heading: The Heading component represents an HTML heading element. - Hero template: A polished marketing hero composed from Fold primitives and design tokens. - Hidden: The Hidden component conceals content from the visible screen while still making it accessible to screen readers. - Hooks: Fold React Hooks provide various pieces of functionality that can make complex logic simple. - Icon: The Icon component displays any SVG icon that is set as a prop. - If: The If component hides content conditionally based on a true/false boolean value. - Image: The Image compoment is used to incorporate a photo or illustration. - Input: The Input component is an element designed for receiving text input from the user, and is an abstraction of the native HTML element. - Kbd: The keyboard key component serves the purpose of indicating which specific key or combination of keys is responsible for executing a particular action. - Layout: Layout components enable the creation of organised and structured document layouts. - Line Chart: The LineChart component plots one or more series of values over a shared axis. - List: The List component is utilized for depicting an HTML list element and its corresponding LI element. - Logo: The Logo component enable users to use the Fold logo anywhere in their app or website. - Menu: The Menu component displays a set of options within a popover element, which becomes visible when the user interacts with an element or performs an action. - Modal: The Modal component provides a useful method for displaying content within a secondary window that opens on top of the main window. - Navigation: Navigation components serve as foundational building blocks for creating extensible navigational hierarchies. - Notification: The Notification component embeds a strip in the document, drawing the user's attention to an important piece of information - Option: The Option component provides the user with the ability to switch between multiple choices. - Pagination: The Pagination component indicates the current page and facilitates navigation among other pages. - Pie Chart: The PieChart component shows how parts contribute to a whole. - Pill: The Pill component serves to convey the status of something, whether it be an entry on a to-do list or user associated with a piece of content. - Popover: The Popover component is an overlay that opens on top of all other content on the page. - Portal: The Portal is employed to transfer any component or element to the end of the document.body and render a React tree within it. - Progress: The Progress component visually communicates progress to the user through color & SVG elements. - Radio: The Radio component is an input element, allowing the user to select a single value from multiple options. - Range: The range component allows the user to define a numeric value that must fall within a specified minimum and maximum range. - Rate: The Rate component generates a row of icons that allows users to choose a rating. - Resizable: The Resizable component creates an adjustable container that can be resized by the user. - Select: The Select component displays a list of options a user can select from. - Skeleton: The Skeleton component creates placeholder previews of components, helping create a more responsive user experience. - SkipNav: The SkipNav component serves as the destination for a link that allows keyboard focus to be directed to the initial element of the main content. - Slider: The Slider component displays a range of values on a horizontal bar, allowing users to choose either a single or a double value. - Sparkline: The Sparkline component is a small SVG powered chart to indicate activity or frequency. - Spinner: The Spinner component is a rotating SVG graphic that informs users that content is currently in the process of loading. - Splitter: The Splitter component generates pane-based layouts that can be adjusted, enlarged, and minimized as needed. - Stack: The Stack component serves as a layout element that evenly distributes child elements with consistent spacing. - Stat: The Stat component highlights key statistics. - Steps: The Steps component conveys progression through a sequence of interconnected stages. - Table: The Table component serves as thin wrapper of the underlying native HTML elements. - Tabs: The Tabs component facilitates the organization of navigation between related content. - Text: The Text component displays HTML text content with the ability to specify what type of tag to use. - Textarea: The Textarea component represents a multi-line plain-text input element. - Timeline: The Timeline component shows a vertically arranged list of events and items. - Toast: The Toast component is a subtle message that displays at the side of the screen without causing disruption. - Toggle: The Toggle component swiftly transitions between two potential states (on/off). - Tooltip: Tooltip components provide users with informative text when they hover over an element. - Upload: The Upload component is a drag & drop area where files can be dropped & then uploaded to an external server. - User List: The User List component represents a list of users with associated actions. - Video: The Video compoment is used to incorporate a video from single or mutliple sources. - View: The View component serves as a fundamental building block within Fold and is internally used by other components. - Virtual: The Virtual component is a element list strategy that can be used to enable infinite scroll. # Accordion > The accordion component is a list of vertically or horizontally stacked headings that collapse or expand associated content. - Package: `@fold-ui/core@0.25.1` - Import public APIs from: `@fold-ui/core` Accordion components are a common user interface pattern. They are often used to create collapsible sections of content on a web page, allowing users to expand or collapse specific sections to focus on the information they're interested in. ## Public components and props ### Accordion | Prop | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `disabled` | `boolean` | No | — | — | | `uncontrolled` | `boolean` | No | — | — | | `iconPosition` | `"start" \| "end"` | No | — | — | | `onChange` | `any` | No | — | — | ### AccordionItem | Prop | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `uncontrolled` | `boolean` | No | — | — | | `collapsed` | `boolean` | No | — | — | | `iconPosition` | `"start" \| "end"` | No | — | — | | `icons` | `AccordionIcons` | No | — | — | | `defaultIcon` | `any` | No | — | — | | `disabled` | `boolean` | No | — | — | | `open` | `boolean` | No | — | — | | `onClick` | `any` | No | — | — | ### AccordionHeading | Prop | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `id` | `string` | No | — | — | | `as` | `Headings` | No | — | — | | `onClick` | `any` | No | — | — | | `open` | `boolean` | No | — | — | | `disabled` | `boolean` | No | — | — | | `icons` | `AccordionIcons` | No | — | — | | `iconSize` | `Size` | No | — | — | | `defaultIcon` | `string` | No | — | — | | `iconPosition` | `"start" \| "end"` | No | — | — | ### AccordionPanel | Prop | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `id` | `string` | No | — | — | | `open` | `boolean` | No | — | default open state for AccodrionPanel | ## CSS variables | Variable | Default | | --- | --- | | `--f-accordion-border-radius` | `var(--f-radius)` | | `--f-accordion-border-color` | `var(--f-color-border)` | | `--f-accordion-border-width` | `1px` | | `--f-accordion-background` | `var(--f-color-surface)` | | `--f-accordion-color` | `var(--f-color-text-weak)` | | `--f-accordion-color-heading` | `var(--f-color-text)` | | `--f-accordion-color-description` | `var(--f-color-text-weakest)` | | `--f-accordion-hover-border-color` | `var(--f-color-border-strong)` | | `--f-accordion-hover-background-color` | `var(--f-color-surface-strong)` | | `--f-accordion-active-background-color` | `var(--f-color-surface-stronger)` | | `--f-accordion-disabled-color` | `var(--f-color-text-weakest)` | | `--f-accordion-active-background` | `var(--f-color-surface-strong)` | | `--f-accordion-active-color` | `var(--f-color-text)` | | `--f-accordion-spacing` | `1rem` | ## Examples Examples may reference local fixture data from the Fold repository; replace those fixtures with application data. ### Imports ```tsx import React from 'react' import { Accordion, AccordionHeading, AccordionItem, AccordionPanel } from '@fold-ui/core' ``` ### Usage ```tsx export const Usage = () => { return ( Section 1 Content for Section 1 goes here. Section 2 Content for Section 2 goes here. ) } ``` ### Basic ```tsx export const Basic = () => { return ( Benefits of using an accordion Accordions reduce clutter & keep users from getting overwhelmed by letting them focus on the information at hand. Typical places to use an accordion FAQ sections, nested navigational items, product information section & content with simple hierarchy. When to avoid using accordions When the user needs access to all of the content on the page, when there is too little content & when the hierarchy of the content is complex. ) } ``` ### IconPosition ```tsx /** * Icon position at the start, instead of the end (default). */ export const IconPosition = () => { return ( Benefits of using an accordion Accordions reduce clutter & keep users from getting overwhelmed by letting them focus on the information at hand. Typical places to use an accordion FAQ sections, nested navigational items, product information section & content with simple hierarchy. When to avoid using accordions When the user needs access to all of the content on the page, when there is too little content & when the hierarchy of the content is complex. ) } ``` ### CustomIcon ```tsx /** * The icon is changeable, however, at the moment the switch animation relies on the default icons and is not available with custom icons. */ export const CustomIcon = () => { return ( Benefits of using an accordion Accordions reduce clutter & keep users from getting overwhelmed by letting them focus on the information at hand. Typical places to use an accordion FAQ sections, nested navigational items, product information section & content with simple hierarchy. When to avoid using accordions When the user needs access to all of the content on the page, when there is too little content & when the hierarchy of the content is complex. ) } ``` ### Uncontrolled ```tsx /** * Uncontrolled Accordion components' AccordionItem children can be collapsed & expanded indepedently of each other. */ export const Uncontrolled = () => { return ( Benefits of using an accordion Accordions reduce clutter & keep users from getting overwhelmed by letting them focus on the information at hand. Typical places to use an accordion FAQ sections, nested navigational items, product information section & content with simple hierarchy. When to avoid using accordions When the user needs access to all of the content on the page, when there is too little content & when the hierarchy of the content is complex. ) } ``` --- # Affix > The affix component acts as a positioning container that allows an element to behave as if it were relatively positioned until it reaches a specified scroll position, at which point it becomes fixed. - Package: `@fold-ui/core@0.25.1` - Import public APIs from: `@fold-ui/core` Affix components are useful for creating navigation menus, headers, or sidebars that stay visible as users scroll through content, improving the overall user experience. It is a wrapper around the "sticky" CSS position property. ## Public components and props ### Affix ## Examples Examples may reference local fixture data from the Fold repository; replace those fixtures with application data. ### Imports ```tsx import { Affix, Text, View } from '@fold-ui/core' import React from 'react' ``` ### Usage ```tsx export const Usage = () => { return ( {(stuck) => {stuck ? 'Content when stuck' : 'Default content'}} Scroll down inside this container. ) } ``` --- # Alert > An alert component is an element that displays a brief, important message in a way that attracts the user's attention without interrupting the user's task. - Package: `@fold-ui/core@0.25.1` - Import public APIs from: `@fold-ui/core` Alerts can serve various purposes, such as presenting information related to errors, indicating the completion of unrelated actions, or providing updates on the status of a system. ## Public components and props ### Alert | Prop | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `alert` | `AlertOptions` | Yes | — | — | | `onDismiss` | `any` | Yes | — | — | ## CSS variables | Variable | Default | | --- | --- | | `--f-alert-padding` | `var(--f-space-inset-x-5)` | | `--f-alert-spacing` | `var(--f-space-5)` | | `--f-alert-icon-color` | `var(--f-color-text-weak)` | ## Examples Examples may reference local fixture data from the Fold repository; replace those fixtures with application data. ### Imports ```tsx import { Alert, Button, useAlert } from '@fold-ui/core' import React, { useEffect } from 'react' ``` ### Usage ```tsx export const Usage = () => { const { alert } = useAlert() const triggerPopup = () => { alert({ icon: 'sun', title: 'Good Morning', description: "And in case I don't see ya, good afternoon, good evening, and good night!", button: 'Okay', closeButton: true, onDismiss: () => console.log('Alert was dismissed!'), }) } return } ``` --- # Aspect Ratio > Aspect Ratio is used to fix the dimensions of a container to a specified aspect ratio based on the width or height. - Package: `@fold-ui/core@0.25.1` - Import public APIs from: `@fold-ui/core` The Aspect Ratio component is useful for constraining proportions of images, video or embedded media. ## Public components and props ### AspectRatio | Prop | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `width` | `string \| number` | No | — | CSS width | | `height` | `string \| number` | No | — | CSS height | | `ratio` | `number` | Yes | — | — | ## Examples Examples may reference local fixture data from the Fold repository; replace those fixtures with application data. ### Imports ```tsx import React from 'react' import { AspectRatio } from '@fold-ui/core' ``` ### WidthBased ```tsx export const WidthBased = () => { return ( 200px x 150px ) } ``` ### HeightBased ```tsx export const HeightBased = () => { return ( 267px x 200px ) } ``` --- # Attachment > The Attachment component displays a file attachment that has been uploaded by a user or the system. - Package: `@fold-ui/core@0.25.1` - Import public APIs from: `@fold-ui/core` The Attachment component is useful for displaying file attachments in message or file-based user interfaces, where it is necessary to represent MIME properties (file sizes, file types, etc.). ## Public components and props ### Attachment | Prop | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `as` | `string` | No | — | — | | `heroPosterHeight` | `number` | No | — | — | | `heroPosterContent` | `ReactNode` | No | — | — | | `heroPoster` | `string` | No | — | — | | `poster` | `string` | No | — | — | | `filesize` | `number` | No | — | — | | `mime` | `string` | No | — | — | | `tools` | `ReactNode` | No | — | — | | `error` | `boolean` | No | — | — | | `size` | `"sm" \| "md" \| "lg"` | No | — | — | | `loading` | `boolean` | No | — | — | | `loadingProgress` | `number` | No | — | — | | `label` | `string` | No | — | — | | `href` | `string` | No | — | — | | `target` | `string` | No | — | — | ### AttachmentThumb | Prop | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `as` | `string` | No | — | — | | `poster` | `string` | No | — | — | | `mime` | `string` | No | — | — | | `error` | `boolean` | No | — | — | | `tools` | `ReactNode` | No | — | — | | `filesize` | `number` | No | — | — | | `loading` | `boolean` | No | — | — | | `loadingProgress` | `number` | No | — | — | | `label` | `string` | No | — | — | | `href` | `string` | No | — | — | ## CSS variables | Variable | Default | | --- | --- | | `--f-attachment-background` | `var(--f-color-surface)` | | `--f-attachment-color` | `var(--f-color-text)` | | `--f-attachment-border-radius` | `var(--f-radius)` | | `--f-attachment-border-color` | `var(--f-color-border)` | | `--f-attachment-border-color-hover` | `var(--f-color-border-strong)` | | `--f-attachment-icon-background` | `var(--f-color-surface-strong)` | | `--f-attachment-icon-color` | `var(--f-color-accent)` | | `--f-attachment-thumb-background` | `var(--f-color-surface)` | | `--f-attachment-thumb-size` | `var(--f-size-28)` | | `--f-attachment-thumb-overlay` | `var(--f-color-overlay)` | | `--f-attachment-padding` | `var(--f-size-1)` | | `--f-attachment-spacing` | `var(--f-size-2)` | | `--f-attachment-shadow` | `var(--f-shadow-sm)` | ## Examples Examples may reference local fixture data from the Fold repository; replace those fixtures with application data. ### Imports ```tsx import { Attachment, AttachmentThumb, IconLib, Text, View } from '@fold-ui/core' import React from 'react' ``` ### Usage ```tsx export const Usage = () => { return ( } /> ) } ``` ### HeroPosterOverlay ```tsx /** * The hero poster provides a useful method to overlay interactive content related to the attachment. This can include (but not limited to) videos & embeddable maps. */ export const HeroPosterOverlay = () => { return ( Not available in your region. } mime="image/png" filesize={24325} label="filename.png" poster="" href="https://fold-ui.com" tools={ } /> ) } ``` ### States ```tsx /** * Incomplete information & error states. */ export const States = () => ( ) ``` ### Size ```tsx /** * Size variations, include `sm`, `md`, `lg`. */ export const Size = () => ( ) ``` ### Thumbnail ```tsx /** * The thumbnail variant of the Attachment component provides a small, more compact version. This can be useful in environment where space is limited, such as inline messages. */ export const Thumbnail = () => ( } /> } /> ) ``` ### ThumbnailRedX ```tsx /** * The `tools` prop is useful for creating various user interaction patterns. Here is a typical red X delete button. */ export const ThumbnailRedX = () => ( } /> ) ``` --- # Audio > The Audio component is used to embed sound content in websites & applications. - Package: `@fold-ui/core@0.25.1` - Import public APIs from: `@fold-ui/core` The Audio component may contain one or more audio sources, represented using the src prop & is a thin wrapper around the native audio element. ## Public components and props ### Audio | Prop | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `autoPlay` | `boolean` | No | — | — | | `muted` | `boolean` | No | — | — | | `controls` | `boolean` | No | — | — | | `srcs` | `AudioSource[]` | Yes | — | — | | `loader` | `boolean` | No | — | — | | `audioProps` | `any` | No | — | — | ### AudioWaveform | Prop | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `defaultProgress` | `number` | No | — | — | | `flatten` | `boolean` | No | — | — | | `samples` | `number` | No | — | — | | `src` | `AudioSource` | Yes | — | — | | `width` | `string \| number` | No | — | CSS width | | `height` | `number` | No | — | CSS height | | `strokeWidth` | `number` | No | — | — | ## CSS variables | Variable | Default | | --- | --- | | `--f-audio-waveform-active` | `var(--f-color-accent)` | | `--f-audio-waveform-inactive` | `var(--f-color-surface-stronger)` | | `--f-audio-waveform-pin-width` | `0.2rem` | | `--f-audio-waveform-pin-height` | `4rem` | | `--f-audio-waveform-pin-background` | `var(--f-color-surface-strongest)` | ## Examples Examples may reference local fixture data from the Fold repository; replace those fixtures with application data. ### Imports ```tsx import { Audio, AudioWaveform, Card } from '@fold-ui/core' import React from 'react' ``` ### Usage ```tsx export const Usage = () => { return (