# Widgetbook Docs Build your Design System's widgets in isolation. ## Docs - [Overview](https://docs.widgetbook.io/): Widgetbook is a sandbox for building **widgets and screens in isolation**. It helps you develop and share hard-to-reach states and edge cases without needing to run your whole app. Widgetbook is [open-source](https://github.com/widgetboo... - [Overview](https://docs.widgetbook.io/cli): The CLI is available as the [widgetbook_cli](https://pub.dev/packages/widgetbook_cli) package. - [Overview](https://docs.widgetbook.io/cloud): Widgetbook Cloud is a managed hosting solution for Widgetbook that allows you to run golden tests on every commit so that you can catch UI regressions before they reach production. - [Quick Start](https://docs.widgetbook.io/quick-start): If you are using Widgetbook in a monorepo, check the [Monorepo](/essentials/monorepo) guide. - [Resources](https://docs.widgetbook.io/resources): Often our users need to create a presentation to convince their team to use Widgetbook. That's why we created the following presentation that you can use to explain your team the value and show them how easy it is to setup the open sourc... - [Telemetry](https://docs.widgetbook.io/telemetry): Widgetbook Generator collects and reports **anonymous** usage information. This information is essential to figure out how we should improve our package. Telemetry does not collect any personal information. - [Accessibility Addon](https://docs.widgetbook.io/addons/accessibility-addon): This addon is **deprecated** due to maintenance issues. Please use the [`BuilderAddon` + `accessibility_tools`](/addons/builder-addon#accessibility_tools) instead. - [Alignment Addon](https://docs.widgetbook.io/addons/alignment-addon): Wraps all use-cases with an [`Align`](https://api.flutter.dev/flutter/widgets/Align-class.html) widget. This is useful when you want to center all your use cases without having to wrap each one of them manually. - [Builder Addon](https://docs.widgetbook.io/addons/builder-addon): The `BuilderAddon` is utility that can help you: - [Custom Addon](https://docs.widgetbook.io/addons/custom-addon): If the built-in addons do not meet your needs, you can create your own custom Addons. This allows you to extend the functionality of Widgetbook and tailor it to your specific requirements. - [Device Frame Addon](https://docs.widgetbook.io/addons/device-frame-addon): This addon will be **deprecated** in v3.15. Please use the [`ViewportAddon`](/addons/viewport-addon) instead. - [Grid Addon](https://docs.widgetbook.io/addons/grid-addon): A utility addon that helps you show grid guidelines behind your use-cases. This is useful for designers and developers to ensure that their components are aligned correctly and follow the design guidelines. - [Inspector Addon](https://docs.widgetbook.io/addons/inspector-addon): The `InspectorAddon`, _built on the ['inspector'](https://pub.dev/packages/inspector) package_, enhances Widgetbook by enabling widget property inspection, such as colors, sizes, and padding, directly in the Workbench. - [Localization Addon](https://docs.widgetbook.io/addons/localization-addon): The `LocalizationAddon` in Widgetbook lets developers preview how widgets behave under different localization settings. This becomes essential when developing applications for a global audience, accommodating differences in language, tex... - [Introduction to Addons](https://docs.widgetbook.io/addons/overview): Addons in Widgetbook provide a flexible and customizable way to enhance your development environment. They allow you to wrap all your use cases with configurable widgets that can be controlled via Widgetbook's UI. - [Semantics Addon](https://docs.widgetbook.io/addons/semantics-addon): This addon is currently **experimental**, so any breaking changes can be introduced at any minor version. - [Text Scale Addon](https://docs.widgetbook.io/addons/text-scale-addon): The `TextScaleAddon` allows developers to adjust the `MediaQuery.textScaler` value to visualize how text scale changes impact layout and rendering. - [Theme Addon](https://docs.widgetbook.io/addons/theme-addon): The Theme Addon lets you inject a theme widget into your tree, to make your use-cases styled and try them out with different themes. There are 3 different variants of the Theme Addon, which depend on the theme data and widget you use in ... - [Time Dilation Addon](https://docs.widgetbook.io/addons/time-dilation-addon): A utility addon designed for modifying the scheduler's [`timeDilation`](https://api.flutter.dev/flutter/scheduler/timeDilation.html) property. - [Viewport Addon](https://docs.widgetbook.io/addons/viewport-addon): The Viewport Addon is an invaluable tool that lets you preview your use-cases on various viewports. These viewports simulate a realistic environment by: - [Zoom Addon](https://docs.widgetbook.io/addons/zoom-addon): A utility addon designed for zooming in/out of the previewed use-case. - [Widgetbook Cloud Reviews](https://docs.widgetbook.io/cloud/reviews): > We are already saving 20% of our time. > – [1KOMMA5°](https://1komma5grad.com/de) _([source](https://youtu.be/Du5yVtnmNzg?t=1759))_ - [Workspaces](https://docs.widgetbook.io/cloud/workspaces): The first step in getting started with Widgetbook Cloud is setting up a workspace for your team. - [Header Widget](https://docs.widgetbook.io/configure/header-widget): You can add a custom header to the navigation panel by providing a `header` parameter to the `Widgetbook` constructor. This can be used for branding or additional information. - [Home Widget](https://docs.widgetbook.io/configure/home-widget): The home widget is a widget that is shown on startup when no use-case is selected. This widget does not inherit from the `appBuilder` or the `addons`; Meaning that if `Theme.of(context)` is called inside this widget, then it will use Wid... - [Initial Route](https://docs.widgetbook.io/configure/initial-route): Initial routes can be used to pick the home page that is used on first launch by providing a `initialRoute` parameter to the `Widgetbook` constructor. - [Leaf Components](https://docs.widgetbook.io/configure/leaf-components): When a component has a single use-case, it's called a leaf component. By default, Widgetbook hides the use-case of the leaf component and displays the component directly in the navigation tree. This helps to declutter the navigation tree... - [Root Widget](https://docs.widgetbook.io/configure/root-widget): All use-cases are wrapped in an root widget (i.e. an `App` widget) to provide a context for the use-cases to render in. - [Scroll Behavior](https://docs.widgetbook.io/configure/scroll-behavior): When running Widgetbook on web or desktop platforms, you might want to customize the scroll behavior to allow dragging with the mouse. This can be useful if you are building widgets that require drag interactions (e.g. [`DraggableScrolla... - [Use-cases Navigation Path](https://docs.widgetbook.io/configure/use-case-nav-path): By default, use-cases have a navigation path in Widgetbook that is based on where their component file is located. There are multiple ways to customize the navigation path either globally or locally. - [Widgetbook's UI Theme](https://docs.widgetbook.io/configure/widgetbook-theme): If you want to change some Widgetbook's UI colors, or want to enforce a specific theme mode, you can do so using these parameters: - [Adding an Example](https://docs.widgetbook.io/contribution/adding-example): Examples serve as practical demonstrations of what can be achieved with the project. Here's how to contribute an example: - [Code Reviews](https://docs.widgetbook.io/contribution/code-reviews): The review process is an essential part of maintaining and improving the overall quality of the project. Here's what to expect: - [Getting Started](https://docs.widgetbook.io/contribution/get-started): Setting up your environment correctly is crucial. This ensures that you can develop features or fix bugs in an environment that mimics the actual development conditions, reducing inconsistencies and issues down the line. Here's a step-by... - [PR Title Conventions](https://docs.widgetbook.io/contribution/pr-conventions): Well-structured commit messages provide a clear project history and make it easier for maintainers and contributors to understand the changes. We use the [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/) format to en... - [Widgetbook Quick Contribution Guide](https://docs.widgetbook.io/contribution/quick-guide): 1. Develop new features. 2. Fix bugs. 3. Improve test coverage. 4. Enhance documentation. 5. Provide examples. - [Synchronize Your Fork](https://docs.widgetbook.io/contribution/sync-your-fork): While working on a forked repository, it's crucial to keep it updated with the original repository. This ensures that you're always working on the latest codebase, which can significantly reduce potential merge conflicts when you're read... - [Ways to Contribute](https://docs.widgetbook.io/contribution/ways-to-contribute): Contributions to Widgetbook aren't limited to just code. We value a diverse set of contributions that can help the project thrive and benefit the community at large. Here are some ways you can make a difference: - [Contribution Workflow](https://docs.widgetbook.io/contribution/workflow): Contributing to a project involves a series of steps to ensure the changes are consistent with the existing codebase and the project's overall goals. Here's a detailed walkthrough of the process: - [Assets](https://docs.widgetbook.io/essentials/assets): If you have a separate package for your design system with its assets, you can skip this guide, because the assets are already included in a separate package. - [Embedding](https://docs.widgetbook.io/essentials/embedding): If you want to embed Widgetbook in your documentation, but you want to hide Widgetbook's UI, you can do so by adding the **`preview` query parameter** to the URL of your hosted Widgetbook. - [Fields](https://docs.widgetbook.io/essentials/fields): Field types form the backbone of Addons and Knobs in Widgetbook. These types define the data that can be manipulated within the Widgetbook environment, enabling users to tweak settings and see their impact in real-time. Each field type c... - [Fonts](https://docs.widgetbook.io/essentials/fonts): If you are using [`google_fonts`](https://pub.dev/packages/google_fonts) package to load custom fonts in your app, you need to pre-load the fonts in Widgetbook, to avoid visual font swaps. - [Widgetbook in a Monorepo](https://docs.widgetbook.io/essentials/monorepo): Widgetbook can be used in a monorepo setup. This guide will show you how to set up Widgetbook in a monorepo. - [What is a Design System?](https://docs.widgetbook.io/glossary/design-system): A design system is a comprehensive set of guidelines, principles, components, and tools that guide the design and development of digital products. It acts as a single source of truth, ensuring consistency across different interfaces and ... - [What are Golden Tests / UI Regression Tests?](https://docs.widgetbook.io/glossary/golden-tests): UI regression tests, commonly referred to as golden tests, are a specialized form of testing aimed at ensuring that visual components of an application do not inadvertently change during code modifications. The "golden" refers to a refer... - [Boolean Knob](https://docs.widgetbook.io/knobs/boolean): The boolean knob renders a toggle switch in the Widgetbook UI where you can dynamically toggle a bool value for a widget property. - [Color Knob](https://docs.widgetbook.io/knobs/color): The color knob renders a combination of a color preview and input fields in the Widgetbook UI where you can dynamically enter a color value for a widget property. - [Custom Knob](https://docs.widgetbook.io/knobs/custom-knob): If the built-in knobs do not meet your needs, you can create your own custom Knobs. This allows you to extend the functionality of Widgetbook and tailor it to your specific requirements. - [DateTime Knob](https://docs.widgetbook.io/knobs/datetime): The DateTime knob renders a DateTime indicator field in the Widgetbook UI where you can enter a DateTime value via a date selector for a widget property. - [Duration Knob](https://docs.widgetbook.io/knobs/duration): The Duration knob renders a set of text fields in the Widgetbook UI where you can dynamically enter a `Duration` value for a widget property. By default, it shows inputs for hours, minutes, and seconds. - [Object Knob](https://docs.widgetbook.io/knobs/object): The object knob allows you to select from a list of objects using different UI controls. This is useful for properties that require a dynamic input with different states or objects of a specific type, such as enums or custom classes. - [Introduction to Knobs](https://docs.widgetbook.io/knobs/overview): Knobs are dynamic tools in Widgetbook that allow you to modify the parameters passed to a use-case on the fly. They allow you to adapt and examine your widgets under various conditions and inputs, enhancing the overall understanding of a... - [String Knob](https://docs.widgetbook.io/knobs/string): The String knob renders a text field in the Widgetbook UI where you can dynamically enter a string value for a widget property. This is particularly useful for properties that require a string input, such as a name or description. - [Annotations](https://docs.widgetbook.io/use-cases/annotations): When importing annotations from `widgetbook_annotation`, we recommend using the `widgetbook` alias to make the code more readable. - [Generate use-cases with LLMs](https://docs.widgetbook.io/use-cases/generate-with-llm): - [Mocking](https://docs.widgetbook.io/use-cases/mocking): Adding a use-case for a widget that has external dependencies can be challenging. In this guide, we'll explore how to mock these dependencies to make cataloging the widget easier. - [What are use-cases?](https://docs.widgetbook.io/use-cases/overview): A Use-case is a specific state or variant of a design component _(or a Flutter widget)_. It is a way to showcase a component in different scenarios. - [`cloud build push`](https://docs.widgetbook.io/cli/commands/cloud-build-push): Pushes a [Widgetbook build](/cloud/builds/overview) to Widgetbook Cloud. - [`coverage`](https://docs.widgetbook.io/cli/commands/coverage): This command is currently **experimental**, so any breaking changes can be introduced at any minor version. - [Billing](https://docs.widgetbook.io/cloud/account/billing): Widgetbook Cloud subscriptions are billed monthly. Your billing cycle begins on the calendar day your subscription starts and renews on the same day each subsequent month. For example, if you start on June 5, the first cycle runs from Ju... - [Privacy Policy](https://docs.widgetbook.io/cloud/account/privacy-policy): Widgetbook GmbH Ausblick 1 33100 Paderborn Germany - [Security Overview](https://docs.widgetbook.io/cloud/account/security): At Widgetbook, security and privacy are at the core of our platform. We are committed to safeguarding your data while ensuring a seamless experience for developing and cataloging your Flutter components. - [Terms of Service](https://docs.widgetbook.io/cloud/account/terms-of-service): "Affiliate" means any entity that directly or indirectly controls, is controlled by, or is under common control with the subject entity. "Control," for purposes of this definition, means direct or indirect ownership or control of more th... - [Access build from Git commit](https://docs.widgetbook.io/cloud/builds/access-from-commit): Since you manage your code with a Git provider, Widgetbook Cloud aims to seamlessly **integrate with your Git provider** to make Widgetbook builds accessible to your team. Therefore, **Widgetbook Cloud links builds to commit statuses** o... - [Overview](https://docs.widgetbook.io/cloud/builds/overview): With _Widgetbook Builds_ developers can host a Widgetbook for each Git commit and make the specific Widgetbook easily accessible for the whole team on Widgetbook Cloud. When setup with CI/CD, you consistantly upload builds for each commi... - [Turbo Builds ⚡](https://docs.widgetbook.io/cloud/builds/turbo): Turbo Builds is a feature that can **save you a lot of time** when pushing builds to Widgetbook Cloud. It works by creating a unique hash for each build depending on it's contents. So if you changed build-irrelevant files (e.g. test file... - [Upload builds](https://docs.widgetbook.io/cloud/builds/upload): A build can be uploaded to Widgetbook Cloud using the Widgetbook CLI. We recommend to setup a CI/CD workflow to automatically upload builds for each commit and branch. - [Setup with Demo Project](https://docs.widgetbook.io/cloud/guides/demo-project): This guide will walk you through setting up a demo project to test Widgetbook Cloud. We'll use the [groceries-demo](https://github.com/widgetbook/groceries-demo) repository as our example project. - [Connect and disconnect project](https://docs.widgetbook.io/cloud/projects/connect): Connected projects automatically synchronize builds with their commit status and link reviews with their associated pull requests, enhancing Widgetbook Cloud's integration into your workflow. - [Create project](https://docs.widgetbook.io/cloud/projects/create): To create a new project, click the `Create project` button on the workspace page. You will be prompted to create a project from a Git repository. Alternatively, you can [create a project manually](/cloud/projects/create#create-project-ma... - [Projects](https://docs.widgetbook.io/cloud/projects/overview): Projects are the central hub for your Widgetbook builds, pull requests, and reviews. - [Figma Reviews](https://docs.widgetbook.io/cloud/reviews/figma): Widgetbook Cloud Review helps verify that developers meet **design requirements** by comparing **Flutter widgets** to their corresponding **Figma designs**. - [Limitations](https://docs.widgetbook.io/cloud/reviews/limitations): The animation limitation has been addressed in the upcoming Widgetbook v4. For more details, check out our [v4 testing guide](https://docs.widgetbook.io/~v4/testing). - [Request a Reviewer](https://docs.widgetbook.io/cloud/reviews/request-reviewer): This feature is currently in **beta**. Please report any issues you encounter and provide feedback regarding improvements. - [Required reviewers](https://docs.widgetbook.io/cloud/reviews/required-reviewer): This feature is currently in **beta**. Please report any issues you encounter and provide feedback regarding improvements. - [Submit a Review](https://docs.widgetbook.io/cloud/reviews/submit): Widgetbook Cloud provides a platform for submitting reviews based on visual diffs, enabling teams to review and discuss visual changes in their projects. - [Multi Snapshot Reviews](https://docs.widgetbook.io/cloud/snapshots/multi-snapshot): If you are using [Widgetbook Cloud Review](/cloud/reviews), you can now create multiple snapshots for a single use case. This feature is useful for testing different states of your use case using various addon or knob configurations, rat... - [Snapshots](https://docs.widgetbook.io/cloud/snapshots/overview): Snapshots is the billing unit of the builds in Widgetbook Cloud. A snapshot is a [addon configuration](/cloud/snapshots/multi-snapshot#multi-snapshot-for-addons) and [knob configuration](/cloud/snapshots/multi-snapshot#multi-snapshot-for... - [Create Visual Pull Requests](https://docs.widgetbook.io/cloud/visual-pull-request/create): Visual pull requests in Widgetbook Cloud are automatically created whenever a Widgetbook project is connected to a Git provider's repository and a code-based pull request is opened. - [Visual Pull Requests](https://docs.widgetbook.io/cloud/visual-pull-request/overview): Unlike code-based pull requests, visual pull requests focus on visual changes in a project. They allow developers to review and discuss user interface changes, ensuring the application's visual aspects meet the desired standards. - [Double Knob](https://docs.widgetbook.io/knobs/double/input): The double input knob renders a text field in the Widgetbook UI where you can dynamically enter a double value for a widget property. This is particularly useful for properties that require a double input, such as a percentage or currency. - [Double Knob](https://docs.widgetbook.io/knobs/double/overview): The double knob renders a text field or slider in the Widgetbook UI where you can dynamically enter a double value for a widget property. This is particularly useful for properties that require a double input, such as a percentage or cur... - [Double Knob](https://docs.widgetbook.io/knobs/double/slider): The double slider knob renders a slider in the Widgetbook UI where you can dynamically enter a double value for a widget property. This is particularly useful for properties that require a double input, such as a percentage or currency. - [Integer Knob](https://docs.widgetbook.io/knobs/integer/input): The integer input knob renders a text field in the Widgetbook UI where you can dynamically enter an int value for a widget property. This is particularly useful for properties that require an integer input, such as shown in a notificatio... - [Integer Knob](https://docs.widgetbook.io/knobs/integer/overview): The integer knob renders a text field or slider in the Widgetbook UI where you can dynamically enter an integer value for a widget property. This is particularly useful for properties that require an integer input, such as a number for a... - [Integer Knob](https://docs.widgetbook.io/knobs/integer/slider): The integer slider knob renders a slider in the Widgetbook UI where you can dynamically enter an integer value for a widget property. This is particularly useful for properties that require an integer input, such as shown in a notificati... - [Iterable Knob](https://docs.widgetbook.io/knobs/iterable/overview): The iterable knob renders a segmented button in the Widgetbook UI where you can dynamically select an iterable value for a widget property. This is particularly useful for properties that require an iterable input, such as a configuratio... - [Iterable Segmented Knob](https://docs.widgetbook.io/knobs/iterable/segmented): The iterable segmented knob allows you to dynamically enter an iterable value for a widget property in the Widgetbook UI. This is particularly useful for properties that require an iterable input, such as a `List` or `Set` of item. - [Object Dropdown Knob](https://docs.widgetbook.io/knobs/object/dropdown): The object knob allows you to dynamically enter an object value for a widget property in the Widgetbook UI. This is particularly useful for properties that require an object input, such as a user profile or an enum value. - [Object Knob](https://docs.widgetbook.io/knobs/object/overview): The object knob renders a segmented button or a dropdown menu in the Widgetbook UI where you can dynamically select an object value for a widget property. This is particularly useful for properties that require an object input, such as a... - [Object Segmented Knob](https://docs.widgetbook.io/knobs/object/segmented): The object segmented knob allows you to dynamically enter an object value for a widget property in the Widgetbook UI. This is particularly useful for properties that require an object input, such as a user profile or an enum value. - [Access builds from Azure commit statuses](https://docs.widgetbook.io/cloud/guides/azure/access-from-commit): Widgetbook Cloud links builds to [Azure commit statuses](https://learn.microsoft.com/en-us/rest/api/azure/devops/git/statuses) so accessing Widgetbook builds integrates seamlessly with your Azure workflow. - [cloud/guides/azure/enforce-reviews](https://docs.widgetbook.io/cloud/guides/azure/enforce-reviews): Depending on your goals and workflow, you may want to enforce reviews for all changes in your project, requiring an accepted Widgetbook review for each pull request with changes. - [Widgetbook Cloud x Azure](https://docs.widgetbook.io/cloud/guides/azure/upload): If you want to use Widgetbook Cloud with your existing Azure DevOps project, here's a step-by-step guide to help you get started. - [Access builds from Bitbucket commit statuses](https://docs.widgetbook.io/cloud/guides/bitbucket/access-from-commit): Widgetbook Cloud links builds to Bitbucket commit statuses so accessing Widgetbook builds integrates seamlessly with your Bitbucket workflow. - [Widgetbook Cloud x Self-hosted Bitbucket](https://docs.widgetbook.io/cloud/guides/bitbucket/self-hosted): If you want to use Widgetbook Cloud with your self-hosted Bitbucket instance (e.g. `bitbucket.acme.com`), here's a pre-requisite guide to help you get started, then you can follow our normal [Bitbucket setup guide](/cloud/guides/bitbucke... - [Widgetbook Cloud x Bitbucket](https://docs.widgetbook.io/cloud/guides/bitbucket/upload): If you want to use Widgetbook Cloud with your existing Bitbucket repository, here's a step-by-step guide to help you get started. - [Widgetbook Cloud x Codemagic](https://docs.widgetbook.io/cloud/guides/codemagic/upload): Codemagic is just a CI/CD platform, which means it needs to be accompanied by a version control system (i.e. [GitHub](/cloud/guides/github/upload), [GitLab](/cloud/guides/gitlab/upload), [Azure](/cloud/guides/azure/upload) or [Bitbucket]... - [Access builds from GitHub commit statuses](https://docs.widgetbook.io/cloud/guides/github/access-from-commit): Widgetbook Cloud links builds to [GitHub commit statuses](https://docs.github.com/en/rest/commits/statuses#about-commit-statuses) so accessing Widgetbook builds integrates seamlessly with your GitHub workflow. - [cloud/guides/github/enforce-reviews](https://docs.widgetbook.io/cloud/guides/github/enforce-reviews): Depending on your goals and workflow, you may want to enforce reviews for all changes in your project, requiring an accepted Widgetbook review for each pull request with changes. - [Upload builds with GitHub Actions](https://docs.widgetbook.io/cloud/guides/github/upload): If you want to use Widgetbook Cloud with your existing GitHub repository, here's a step-by-step guide to help you get started. - [Access builds from GitLab commit statuses](https://docs.widgetbook.io/cloud/guides/gitlab/access-from-commit): Widgetbook Cloud links builds to [GitLab commit statuses](https://docs.gitlab.com/api/commits/#commit-status) so accessing Widgetbook builds integrates seamlessly with your GitLab workflow. - [Widgetbook Cloud x Self-managed GitLab](https://docs.widgetbook.io/cloud/guides/gitlab/self-managed): This guide works for both **GitLab self-managed** and **GitLab Dedicated**. - [Widgetbook Cloud x GitLab](https://docs.widgetbook.io/cloud/guides/gitlab/upload): If you want to use Widgetbook Cloud with your existing GitLab repository, here's a step-by-step guide to help you get started. - [Email Notifications](https://docs.widgetbook.io/cloud/reviews/notifications/email): Widgetbook Cloud sends email notifications to keep reviewers informed about pull request assignments and review status changes. - [Slack Notifications](https://docs.widgetbook.io/cloud/reviews/notifications/slack): Widgetbook Cloud integrates with Slack to keep your team informed about visual pull requests that need review. Notifications are sent automatically to your Slack workspace, ensuring that reviews don't go unnoticed.