# Introduction to Knobs

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 component's behavior.

<Image src="/assets/knobs/knobs.png" zoom />

## Usage

To incorporate knobs into your widgets, use the `context.knobs` function to access the knobs builder:

```dart title="Example: Knobs"
import 'package:flutter/material.dart';
import 'package:widgetbook/widgetbook.dart';
import 'package:widgetbook_annotation/widgetbook_annotation.dart' as widgetbook;

import '../main.dart';

@widgetbook.UseCase(name: 'with different title', type: Container)
Widget myWidget(BuildContext context) {
  return MyHomePage(
    title: context.knobs.string(
      label: 'Title Label',
      initialValue: 'HomePage',
    ),
  );
}
```

## Properties

Each Knob possesses a set of inherent properties to control its display in the Widgetbook's UI:

<Accordion title="Knob" defaultOpen>
  <Property name="label" type="String" required>
    A String that provides a title to the Knob. Each label must be unique for a WidgetbookUseCase.
  </Property>

  ---

  <Property name="initialValue" type="T" optional>
    The initial value of the knob when the WidgetbookUseCase is loaded. 
    The accepted type depends on the Knob. For instance, a [Non-nullable Integer Knob](/knobs/integer/overview) accepts `int` as a type. 
    The default value depends on the specifics of the knob but is `null` for nullable knobs.
  </Property>

  ---

  <Property name="description" type="String" optional>
    An optional String that explains the Knob's functionality. 
    It serves as a form of documentation within Widgetbook, assisting your team members in understanding how to manipulate the Knob.
  </Property>
</Accordion>

## Available Knobs

| Type                             | Regular Knob                                                                  | Nullable Knob                                                                             | Multi-snapshot Support                                                 |
| -------------------------------- | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| [bool](/knobs/boolean)           | [boolean](/knobs/boolean#contextknobsboolean)                                 | [booleanOrNull](/knobs/boolean#contextknobsbooleanornull)                                 | [BooleanKnobConfig](/knobs/boolean#multi-snapshot-support)             |
| [int](/knobs/integer/overview)   | [int.input](/knobs/integer/input#contextknobsintinput)                        | [int.input](/knobs/integer/input#contextknobsintornullinput)                              | [IntKnobConfig](/knobs/integer/input#multi-snapshot-support)           |
| [int](/knobs/integer/overview)   | [int.slider](/knobs/integer/slider#contextknobsintslider)                     | [int.slider](/knobs/integer/slider#contextknobsintornullslider)                           | [IntKnobConfig](/knobs/integer/slider#multi-snapshot-support)          |
| [double](/knobs/double/overview) | [double.input](/knobs/double/input#contextknobsdoubleinput)                   | [doubleOrNull.input](/knobs/double/input#contextknobsdoubleornullinput)                   | [DoubleKnobConfig](/knobs/double/input#multi-snapshot-support)         |
| [double](/knobs/double/overview) | [double.slider](/knobs/double/slider#contextknobsdoubleslider)                | [doubleOrNull.slider](/knobs/double/slider#contextknobsdoubleornullslider)                | [DoubleKnobConfig](/knobs/double/slider#multi-snapshot-support)        |
| [String](/knobs/string)          | [string](/knobs/string#contextknobsstring)                                    | [stringOrNull](/knobs/string#contextknobsstringornull)                                    | [StringKnobConfig](/knobs/string#multi-snapshot-support)               |
| [Duration](/knobs/duration)      | [duration](/knobs/duration#contextknobsduration)                              | [durationOrNull](/knobs/duration#contextknobsdurationornull)                              | [DurationKnobConfig](/knobs/duration#multi-snapshot-support)           |
| [DateTime](/knobs/datetime)      | [dateTime](/knobs/datetime#contextknobsdatetime)                              | [dateTimeOrNull](/knobs/datetime#contextknobsdatetimeornull)                              | [DateTimeKnobConfig](/knobs/datetime#multi-snapshot-support)           |
| [Color](/knobs/color)            | [color](/knobs/color#contextknobscolor)                                       | [colorOrNull](/knobs/color#contextknobscolorornull)                                       | [ColorKnobConfig](/knobs/color#multi-snapshot-support)                 |
| [T](/knobs/iterable/overview)    | [iterable.segmented](/knobs/iterable/segmented#contextknobsiterablesegmented) | [iterableOrNull.segmented](/knobs/iterable/segmented#contextknobsiterableornullsegmented) | [IterableKnobConfig](/knobs/iterable/segmented#multi-snapshot-support) |
| [T](/knobs/object/overview)      | [object.dropdown](/knobs/object/dropdown#contextknobsobjectdropdown)          | [objectOrNull.dropdown](/knobs/object/dropdown#contextknobsobjectornulldropdown)          | [ObjectKnobConfig](/knobs/object/dropdown#multi-snapshot-support)      |
| [T](/knobs/object/overview)      | [object.segmented](/knobs/object/segmented#contextknobsobjectsegmented)       | [objectOrNull.segmented](/knobs/object/segmented#contextknobsobjectornullsegmented)       | [ObjectKnobConfig](/knobs/object/segmented#multi-snapshot-support)     |