DOCSEARCHbyAlgolia
Submit Docs

Lookbook Documentation

repository·main·Indexed 22 days ago

https://github.com/lookbook-hq/lookbook

A UI development environment for Ruby on Rails that provides a component browser and preview system. Lookbook supports ViewComponent, Phlex, and ActionView partials to help developers build and document modular user interfaces.

Tokens
25.8K
Snippets
105
Records
153
Agent score
77%

What's inside Lookbook

  1. Introduction to Lookbook

    main

    Lookbook is an open-source UI development tool designed for building modular front-end UIs in Ruby on Rails applications. It provides a web interface for browsing and previewing UI components, allowing developers to develop, test, and document components in isolation.

    While originally built for ViewComponent-based projects, it now supports various other component types.

  2. What is Lookbook?

    main

    Lookbook is a UI development environment for Ruby on Rails applications. It provides a component browser, a preview system, and an integrated documentation engine to help teams build modular and maintainable user interfaces.

    It is compatible with several view technologies, including:

    • ViewComponent
    • Phlex
    • ActionView partials

  3. Ways to extend Lookbook

    main

    Lookbook is designed to be extensible to meet specific project requirements. You can extend its functionality through the following mechanisms:

    • Bespoke preview inspector panels: Add custom panels to the inspector to display additional information about your components.
    • Custom input fields: Implement custom inputs to customize the live-editing experience for preview parameters.
    • New tags: Define custom tags for use when annotating preview files.
    • Callbacks (Hooks): Register callbacks to tap into specific events that occur while Lookbook is running.

  4. Understand the Lookbook Ruby API usage guidelines

    main

    The Lookbook Ruby API provides tools for interacting with Lookbook components and themes.

    Important Note on API Stability: Only documented classes, attributes, and methods should be considered part of the public API. Any undocumented elements should be treated as private. These private elements are subject to change or removal in future releases without prior deprecation notice.

  5. Use Lifecycle Hooks to trigger external actions

    main

    Lookbook provides lifecycle hooks that allow you to trigger actions outside of the Lookbook application during specific stages of its lifecycle. These hooks are registered during the Lookbook installation configuration.

    All hook callback blocks receive the main Lookbook application object as the first argument. Some hooks provide additional arguments depending on the specific hook being used.

  7. Create preview classes for components

    main

    To preview a component in Lookbook, you must create an associated preview class.

    Implementation details:

    • Location: Create preview classes within the test/components/previews directory.
    • Inheritance: Preview classes must extend Lookbook::Preview or ViewComponent::Preview.
    • Organization: You can organize previews into sub-directories; Lookbook will reflect this directory structure in its navigation menu.

  8. Distinguish between code extensions and UI customization

    main

    When modifying Lookbook, distinguish between code-based extensions and UI customization:

    • Code Extensions: Use the extension points (panels, inputs, tags, and hooks) to add new logic or functional capabilities.
    • UI Customization: For visual changes like theming, do not use code extensions. Instead, use the configuration system or refer to the UI customization section in the User Guide.

  9. How Lookbook previews work

    main

    Lookbook uses Preview classes to provide illustrative examples (scenarios) of how components should be used.

    • Mapping: Typically, there is a 1-to-1 mapping where each component has its own dedicated preview class.
    • Compatibility: Lookbook is fully compatible with ViewComponent's native preview system. Existing ViewComponent::Preview classes will automatically appear in the Lookbook UI.
    • Scenarios: Each public method defined within a preview class represents a unique scenario. Lookbook generates an isolated preview for each public method and adds it to the navigation. Private methods are ignored and will not appear in the navigation.
    # test/components/previews/button_component_preview.rb
class ButtonComponentPreview < Lookbook::Preview
  def standard
    render ButtonComponent.new(text: "Click me")
  end

  def with_icon
    render ButtonComponent.new(text: "Launch spaceship", icon: "rocket")
  end

  private

  # Private methods are ignored and will not show up in the navigation
  def not_a_scenario
    # ...
  end
end

  10. Understand Lookbook Scenarios

    main

    A scenario is defined by a single method within a Preview class.

    A scenario provides a specific example of a component being rendered with a particular set of parameters. This concept is analogous to 'stories' in Storybook.

    In the Lookbook API, scenarios are represented by ScenarioEntity objects.

  11. When to use Lookbook vs Storybook

    main

    Choosing between Lookbook and Storybook depends on your application's architecture:

    • Use Storybook if you are building UIs with JavaScript frameworks like Vue or React.
    • Use Lookbook if you are working with Ruby-based, server-side rendered component frameworks in Rails (such as ViewComponent, Phlex, or regular ActionView template partials). Lookbook is designed to integrate seamlessly into Rails projects without the complex custom setups often required to make Storybook work with server-side components.

    Tip: If you are using ViewComponent and want to evaluate Storybook, consider using ViewComponent Storybook to bridge the gap between Rails and Storybook.