vaadin-framework/documentation/clientside/clientside-widget.asciidoc

---
title: Creating a Custom Widget
order: 5
layout: page
---

[[clientside.widget]]
= Creating a Custom Widget

Creating a new Vaadin component usually begins from making a client-side widget,
which is later integrated with a server-side counterpart to enable server-side
development. In addition, you can also choose to make pure client-side widgets,
a possibility which we also describe later in this section.

[[clientside.widget.simple]]
== A Basic Widget

All widgets extend the [classname]#Widget# class or some of its subclasses. You
can extend any core GWT or supplementary Vaadin widgets. Perhaps typically, an
abstraction such as [classname]#Composite#. The basic GWT widget component
hierarchy is illustrated in <<figure.clientside.widgets>>. Please see the GWT
API documentation for a complete description of the widget classes.

[[figure.clientside.widgets]]
.GWT widget base class hierarchy
image::img/gwt-widgets-hi.png[]

For example, we could extend the [classname]#Label# widget to display some
custom text.

----
package com.example.myapp.client;

import com.google.gwt.user.client.ui.Label;

public class MyWidget extends Label {
    public static final String CLASSNAME = "mywidget";

    public MyWidget() {
        setStyleName(CLASSNAME);
        setText("This is MyWidget");
    }
}
----

The above example is largely what the Eclipse plugin generates as a widget stub.
It is a good practice to set a distinctive style class for the widget, to allow
styling it with CSS.

The client-side source code __must__ be contained in a [filename]#client#
package under the package of the descriptor file, which is covered later.


[[clientside.widget.using]]
== Using the Widget

You can use a custom widget just like you would use any widget, possibly
integrating it with a server-side component, or in pure client-side modules such
as the following:


----
public class MyEntryPoint implements EntryPoint {
    @Override
    public void onModuleLoad() {
        // Use the custom widget
        final MyWidget mywidget = new MyWidget();
        RootPanel.get().add(mywidget);
    }
}
----