how to use annotation with create_widget

docs/howtos/extending/magicgui.md

@@ -178,6 +178,10 @@ The following napari types may be used as *parameter* type annotations in
   {attr}`napari.types.ImageData` or  {attr}`napari.types.LabelsData`
 - {class}`napari.Viewer`
 
+```{note}
+If you're interested in getting synchronized information from the napari viewer into widgets without `@magicgui`, see the [`create_widget` example](#magicgui-widgets-create_widget) below.
+```
+
 The consequence of each type annotation is described below:
 
 #### Annotating as a `Layer` subclass
@@ -783,3 +787,41 @@ viewer.window.add_dock_widget(my_widg)
 
 As above to turn this into a [plugin widget contribution](widgets-contribution-guide),
 simply provide the class definition and add to the plugin manifest.
+
+#### `magicgui.widgets.create_widget`
+
+You might want to add a layer selection as [shown above](#parameter-annotations) into your highly customizable `QtWidgets.QWidget` that is always synchronized with the available {attr}`napari.types.ImageData` layers in your viewer. For this you can use the {func}`create_widget <magicgui.widgets.create_widget>` function as described in the following example.
+
+To synchronize the information between the napari viewer (i.e. the available layers) the function `reset_choices` of the dropdown widget needs to be connected to the `inserted`, `removed` and `reordered` events of the `viewer.layers` as is done in the `__init__` function below:
+
+```python
+import napari
+from magicgui.widgets import create_widget
+from qtpy.QtWidgets import QWidget, QHBoxLayout
+
+from napari.types import ImageData
+
+
+class ExampleLayerListWidget(QWidget):
+    def __init__(self, viewer: "napari.viewer.Viewer"):
+        super().__init__()
+        self.viewer = viewer
+
+        # create new widget with create_widget and type annotation
+        self.layer_select = create_widget(annotation=ImageData)
+        layers_events = self.viewer.layers.events
+        layers_events.inserted.connect(self.layer_select.reset_choices)
+        layers_events.removed.connect(self.layer_select.reset_choices)
+        layers_events.reordered.connect(self.layer_select.reset_choices)
+
+        self.setLayout(QHBoxLayout())
+        # add it to the layout
+        self.layout().addWidget(self.layer_select.native)
+
+# Create a `viewer`
+viewer = napari.Viewer()
+# Instantiate your widget
+my_widg = ExampleLayerListWidget(viewer)
+# Add widget to `viewer`
+viewer.window.add_dock_widget(my_widg)
+```