---
title: "Create Widget"
method: POST
path: "/api/v3/meta/bases/{baseId}/dashboards/{dashboardId}/widgets"
tags: ["Dashboards"]
---

# Create Widget

`POST /api/v3/meta/bases/{baseId}/dashboards/{dashboardId}/widgets`

## Request

- Base URL: `https://app.nocodb.com`
- URL: `https://app.nocodb.com/api/v3/meta/bases/{baseId}/dashboards/{dashboardId}/widgets`
- Auth: one of:
  - API key in header `xc-token`
  - HTTP bearer
- TypeScript: <https://skmtc.dev/nocodb/apis/nocodb-v3/docs/api/v3/meta/bases/:baseId/dashboards/:dashboardId/widgets/post.ts> (a function with typed inputs; its response is checked against the schema)

Create a new widget within the specified dashboard.

**Note**: Widget APIs are available on cloud-hosted **Enterprise** plans, and on licensed self-hosted deployments (**Business** plan and above).

## Path parameters

- `baseId` string, required
- `dashboardId` string, required

## Request body

- WidgetCreateReq: Widget create request body
  - `title` string, required: Title of the widget.
  - `description` string, nullable: Description of the widget.
  - `type` 'chart' | 'metric' | 'text' | 'iframe', required: Type of the widget. `gauge`, `table` and `pivot` exist and are returned by read, but are not accepted here yet.
  - `options` union: Widget configuration. `anyOf`, not `oneOf`: the metric, text and iframe shapes constrain nothing, so they overlap every chart body by construction.
    - WidgetOptionsMetric: Options for a metric widget (type=metric).
      - `data_source` 'table' | 'view' | 'filter': Data source type.
      - `metric` object: Metric aggregation configuration.
        - `type` 'count' | 'summary', required: 'count' counts all rows, 'summary' aggregates a column.
        - `field_id` string: Column to aggregate. Required when type is 'summary'.
        - `aggregation` 'sum' | 'avg' | 'count' | 'min' | 'max', required: Aggregation function.
      - `appearance` object
        - `type` 'default' | 'filled' | 'coloured': Visual style variant.
        - `theme` 'gray' | 'red' | 'green' | 'yellow' | 'pink' | 'blue' | 'orange' | 'maroon' | 'purple': Color theme.
    - WidgetOptionsText: Options for a text widget (type=text). Formatting is nested inside appearance.
      - `content` string: Text content (plain text or markdown).
      - `type` 'markdown' | 'text': Text rendering mode.
      - `appearance` object
        - `formatting` object: Text formatting options.
          - `horizontal_align` 'flex-start' | 'center' | 'flex-end'
          - `vertical_align` 'flex-start' | 'center' | 'flex-end'
          - `bold` boolean
          - `italic` boolean
          - `underline` boolean
          - `strikethrough` boolean
        - `font` object: Font settings (only for type=text).
          - `family` string
          - `weight` 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900
          - `size` number: Font size in pixels.
          - `line_height` number: Line height multiplier.
        - `color` string: Hex color (only for type=text).
    - WidgetOptionsIframe: Options for an iframe widget (type=iframe).
      - `url` string: URL to embed.
      - `allow_fullscreen` boolean: Whether to allow fullscreen.
    - WidgetOptionsPieChart: Options for a pie chart widget (type=chart, chart_type=pie).
      - `chart_type` 'pie', required
      - `data_source` 'table' | 'view' | 'filter'
      - `data` object
        - `category` object
          - `field_id` string, required: Column to group by.
          - `order_by` 'default' | 'asc' | 'desc'
          - `category_limit` number: Max categories (10-50).
          - `include_empty_records` boolean
          - `include_others` boolean: Aggregate remaining into 'Others'.
        - `value` object
          - `type` 'count' | 'summary', required
          - `field_id` string: Column to aggregate. Required when type is 'summary'.
          - `aggregation` string: Aggregation function. Required when type is 'summary'.
      - `appearance` object
        - `size` 'small' | 'medium' | 'large'
        - `show_count_in_legend` boolean
        - `show_percentage_on_chart` boolean
        - `legend_position` 'top' | 'right' | 'bottom' | 'left' | 'none'
        - `color_schema` 'default' | 'classic' | 'vibrant' | 'pastel' | 'earth' | 'monoBlue' | 'custom'
        - `custom_color_schema` object[]
          - `color` string
          - `label` string
    - WidgetOptionsDonutChart: Options for a donut chart widget (type=chart, chart_type=donut). Same structure as pie chart.
      - `chart_type` 'donut', required
      - `data_source` 'table' | 'view' | 'filter'
      - `data` object
        - `category` object
          - `field_id` string, required
          - `order_by` 'default' | 'asc' | 'desc'
          - `category_limit` number
          - `include_empty_records` boolean
          - `include_others` boolean
        - `value` object
          - `type` 'count' | 'summary', required
          - `field_id` string
          - `aggregation` string
      - `appearance` object
        - `size` 'small' | 'medium' | 'large'
        - `show_count_in_legend` boolean
        - `show_percentage_on_chart` boolean
        - `legend_position` 'top' | 'right' | 'bottom' | 'left' | 'none'
        - `color_schema` 'default' | 'classic' | 'vibrant' | 'pastel' | 'earth' | 'monoBlue' | 'custom'
        - `custom_color_schema` object[]
          - `color` string
          - `label` string
    - WidgetOptionsBarChart: Options for a bar chart widget (type=chart, chart_type=bar).
      - `chart_type` 'bar', required
      - `data_source` 'table' | 'view' | 'filter'
      - `data` object
        - `x_axis` object: X-axis (category) configuration.
          - `field_id` string, required: X-axis grouping field.
          - `sort_by` 'x_axis' | 'y_axis': Sort by x-axis labels or y-axis values.
          - `order_by` 'default' | 'asc' | 'desc'
          - `include_empty_records` boolean
          - `include_others` boolean
          - `category_limit` number: Max categories (10-50).
        - `y_axis` object: Y-axis (value) configuration.
          - `start_at_zero` boolean
          - `fields` object[]: Fields to aggregate on the y-axis.
            - `field_id` string, required
            - `aggregation` string, required
          - `group_by` string, nullable: Optional secondary grouping field ID.
      - `appearance` object
        - `size` 'small' | 'medium' | 'large'
        - `show_count_in_legend` boolean
        - `show_value_in_chart` boolean
        - `legend_position` 'top' | 'right' | 'bottom' | 'left' | 'none'
        - `color_schema` 'default' | 'classic' | 'vibrant' | 'pastel' | 'earth' | 'monoBlue' | 'custom'
    - WidgetOptionsLineChart: Options for a line chart widget (type=chart, chart_type=line). Same data structure as bar chart with additional line-specific appearance options.
      - `chart_type` 'line', required
      - `data_source` 'table' | 'view' | 'filter'
      - `data` object
        - `x_axis` object
          - `field_id` string, required
          - `sort_by` 'x_axis' | 'y_axis'
          - `order_by` 'default' | 'asc' | 'desc'
          - `include_empty_records` boolean
          - `include_others` boolean
          - `category_limit` number
        - `y_axis` object
          - `start_at_zero` boolean
          - `fields` object[]
            - `field_id` string, required
            - `aggregation` string, required
          - `group_by` string, nullable
      - `appearance` object
        - `size` 'small' | 'medium' | 'large'
        - `smooth_lines` boolean: Smooth curve vs straight line segments.
        - `plot_data_points` boolean: Show dots at data points.
        - `show_count_in_legend` boolean
        - `show_value_in_chart` boolean
        - `legend_position` 'top' | 'right' | 'bottom' | 'left' | 'none'
        - `color_schema` 'default' | 'classic' | 'vibrant' | 'pastel' | 'earth' | 'monoBlue' | 'custom'
    - WidgetOptionsScatter: Options for a scatter plot widget (type=chart, chart_type=scatter). Same data structure as bar chart.
      - `chart_type` 'scatter', required
      - `data_source` 'table' | 'view' | 'filter'
      - `data` object
        - `x_axis` object
          - `field_id` string, required
          - `sort_by` 'x_axis' | 'y_axis'
          - `order_by` 'default' | 'asc' | 'desc'
          - `include_empty_records` boolean
          - `include_others` boolean
          - `category_limit` number
        - `y_axis` object
          - `start_at_zero` boolean
          - `fields` object[]
            - `field_id` string, required
            - `aggregation` string, required
          - `group_by` string, nullable
      - `appearance` object
        - `size` 'small' | 'medium' | 'large'
        - `show_count_in_legend` boolean
        - `show_value_in_chart` boolean
        - `legend_position` 'top' | 'right' | 'bottom' | 'left' | 'none'
        - `color_schema` 'default' | 'classic' | 'vibrant' | 'pastel' | 'earth' | 'monoBlue' | 'custom'
  - `position` object: Position and size of the widget on the dashboard grid.
    - `x` number: Column position of the widget on the dashboard grid (0-indexed, left to right). e.g. 0 means the first column, 6 means starting at the 7th column.
    - `y` number: Row position of the widget on the dashboard grid (0-indexed, top to bottom). e.g. 0 means the first row, 4 means starting at the 5th row.
    - `w` number: Width of the widget in grid columns. e.g. 6 means the widget spans 6 columns (half of a 12-column grid).
    - `h` number: Height of the widget in grid rows. e.g. 4 means the widget spans 4 rows tall.
  - `table_id` string, nullable: Unique identifier for the associated table.
  - `view_id` string, nullable: Unique identifier for the associated view.

## Response `200`

Widget created.

- WidgetRead
  - `id` string, required: Unique identifier for the widget.
  - `title` string, required: Title of the widget.
  - `description` string, nullable: Description of the widget.
  - `dashboard_id` string, required: Unique identifier for the parent dashboard.
  - `type` 'chart' | 'metric' | 'gauge' | 'table' | 'pivot' | 'text' | 'iframe', required: Type of the widget. `gauge`, `table` and `pivot` widgets are returned here but cannot yet be created or updated through this API — create them in the dashboard editor.
  - `options` union: Widget configuration. Structure depends on widget type. The branches below cover `metric`, `text`, `iframe` and `chart` with `chart_type` pie, donut, bar, line or scatter. A `gauge`, `table` or `pivot` widget, or a chart with `chart_type: treemap`, is returned with an options shape that is not modelled here yet and matches the open branch instead.
    - WidgetOptionsMetric: Options for a metric widget (type=metric).
      - `data_source` 'table' | 'view' | 'filter': Data source type.
      - `metric` object: Metric aggregation configuration.
        - `type` 'count' | 'summary', required: 'count' counts all rows, 'summary' aggregates a column.
        - `field_id` string: Column to aggregate. Required when type is 'summary'.
        - `aggregation` 'sum' | 'avg' | 'count' | 'min' | 'max', required: Aggregation function.
      - `appearance` object
        - `type` 'default' | 'filled' | 'coloured': Visual style variant.
        - `theme` 'gray' | 'red' | 'green' | 'yellow' | 'pink' | 'blue' | 'orange' | 'maroon' | 'purple': Color theme.
    - WidgetOptionsPieChart: Options for a pie chart widget (type=chart, chart_type=pie).
      - `chart_type` 'pie', required
      - `data_source` 'table' | 'view' | 'filter'
      - `data` object
        - `category` object
          - `field_id` string, required: Column to group by.
          - `order_by` 'default' | 'asc' | 'desc'
          - `category_limit` number: Max categories (10-50).
          - `include_empty_records` boolean
          - `include_others` boolean: Aggregate remaining into 'Others'.
        - `value` object
          - `type` 'count' | 'summary', required
          - `field_id` string: Column to aggregate. Required when type is 'summary'.
          - `aggregation` string: Aggregation function. Required when type is 'summary'.
      - `appearance` object
        - `size` 'small' | 'medium' | 'large'
        - `show_count_in_legend` boolean
        - `show_percentage_on_chart` boolean
        - `legend_position` 'top' | 'right' | 'bottom' | 'left' | 'none'
        - `color_schema` 'default' | 'classic' | 'vibrant' | 'pastel' | 'earth' | 'monoBlue' | 'custom'
        - `custom_color_schema` object[]
          - `color` string
          - `label` string
    - WidgetOptionsDonutChart: Options for a donut chart widget (type=chart, chart_type=donut). Same structure as pie chart.
      - `chart_type` 'donut', required
      - `data_source` 'table' | 'view' | 'filter'
      - `data` object
        - `category` object
          - `field_id` string, required
          - `order_by` 'default' | 'asc' | 'desc'
          - `category_limit` number
          - `include_empty_records` boolean
          - `include_others` boolean
        - `value` object
          - `type` 'count' | 'summary', required
          - `field_id` string
          - `aggregation` string
      - `appearance` object
        - `size` 'small' | 'medium' | 'large'
        - `show_count_in_legend` boolean
        - `show_percentage_on_chart` boolean
        - `legend_position` 'top' | 'right' | 'bottom' | 'left' | 'none'
        - `color_schema` 'default' | 'classic' | 'vibrant' | 'pastel' | 'earth' | 'monoBlue' | 'custom'
        - `custom_color_schema` object[]
          - `color` string
          - `label` string
    - WidgetOptionsBarChart: Options for a bar chart widget (type=chart, chart_type=bar).
      - `chart_type` 'bar', required
      - `data_source` 'table' | 'view' | 'filter'
      - `data` object
        - `x_axis` object: X-axis (category) configuration.
          - `field_id` string, required: X-axis grouping field.
          - `sort_by` 'x_axis' | 'y_axis': Sort by x-axis labels or y-axis values.
          - `order_by` 'default' | 'asc' | 'desc'
          - `include_empty_records` boolean
          - `include_others` boolean
          - `category_limit` number: Max categories (10-50).
        - `y_axis` object: Y-axis (value) configuration.
          - `start_at_zero` boolean
          - `fields` object[]: Fields to aggregate on the y-axis.
            - `field_id` string, required
            - `aggregation` string, required
          - `group_by` string, nullable: Optional secondary grouping field ID.
      - `appearance` object
        - `size` 'small' | 'medium' | 'large'
        - `show_count_in_legend` boolean
        - `show_value_in_chart` boolean
        - `legend_position` 'top' | 'right' | 'bottom' | 'left' | 'none'
        - `color_schema` 'default' | 'classic' | 'vibrant' | 'pastel' | 'earth' | 'monoBlue' | 'custom'
    - WidgetOptionsLineChart: Options for a line chart widget (type=chart, chart_type=line). Same data structure as bar chart with additional line-specific appearance options.
      - `chart_type` 'line', required
      - `data_source` 'table' | 'view' | 'filter'
      - `data` object
        - `x_axis` object
          - `field_id` string, required
          - `sort_by` 'x_axis' | 'y_axis'
          - `order_by` 'default' | 'asc' | 'desc'
          - `include_empty_records` boolean
          - `include_others` boolean
          - `category_limit` number
        - `y_axis` object
          - `start_at_zero` boolean
          - `fields` object[]
            - `field_id` string, required
            - `aggregation` string, required
          - `group_by` string, nullable
      - `appearance` object
        - `size` 'small' | 'medium' | 'large'
        - `smooth_lines` boolean: Smooth curve vs straight line segments.
        - `plot_data_points` boolean: Show dots at data points.
        - `show_count_in_legend` boolean
        - `show_value_in_chart` boolean
        - `legend_position` 'top' | 'right' | 'bottom' | 'left' | 'none'
        - `color_schema` 'default' | 'classic' | 'vibrant' | 'pastel' | 'earth' | 'monoBlue' | 'custom'
    - WidgetOptionsScatter: Options for a scatter plot widget (type=chart, chart_type=scatter). Same data structure as bar chart.
      - `chart_type` 'scatter', required
      - `data_source` 'table' | 'view' | 'filter'
      - `data` object
        - `x_axis` object
          - `field_id` string, required
          - `sort_by` 'x_axis' | 'y_axis'
          - `order_by` 'default' | 'asc' | 'desc'
          - `include_empty_records` boolean
          - `include_others` boolean
          - `category_limit` number
        - `y_axis` object
          - `start_at_zero` boolean
          - `fields` object[]
            - `field_id` string, required
            - `aggregation` string, required
          - `group_by` string, nullable
      - `appearance` object
        - `size` 'small' | 'medium' | 'large'
        - `show_count_in_legend` boolean
        - `show_value_in_chart` boolean
        - `legend_position` 'top' | 'right' | 'bottom' | 'left' | 'none'
        - `color_schema` 'default' | 'classic' | 'vibrant' | 'pastel' | 'earth' | 'monoBlue' | 'custom'
    - WidgetOptionsText: Options for a text widget (type=text). Formatting is nested inside appearance.
      - `content` string: Text content (plain text or markdown).
      - `type` 'markdown' | 'text': Text rendering mode.
      - `appearance` object
        - `formatting` object: Text formatting options.
          - `horizontal_align` 'flex-start' | 'center' | 'flex-end'
          - `vertical_align` 'flex-start' | 'center' | 'flex-end'
          - `bold` boolean
          - `italic` boolean
          - `underline` boolean
          - `strikethrough` boolean
        - `font` object: Font settings (only for type=text).
          - `family` string
          - `weight` 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900
          - `size` number: Font size in pixels.
          - `line_height` number: Line height multiplier.
        - `color` string: Hex color (only for type=text).
    - WidgetOptionsIframe: Options for an iframe widget (type=iframe).
      - `url` string: URL to embed.
      - `allow_fullscreen` boolean: Whether to allow fullscreen.
    - object: Options for a widget type whose shape is not modelled above.
  - `order` number, nullable: Display order of the widget.
  - `position` object, nullable: Position and size of the widget on the dashboard grid.
    - `x` number: Column position of the widget on the dashboard grid (0-indexed, left to right). e.g. 0 means the first column, 6 means starting at the 7th column.
    - `y` number: Row position of the widget on the dashboard grid (0-indexed, top to bottom). e.g. 0 means the first row, 4 means starting at the 5th row.
    - `w` number: Width of the widget in grid columns. e.g. 6 means the widget spans 6 columns (half of a 12-column grid).
    - `h` number: Height of the widget in grid rows. e.g. 4 means the widget spans 4 rows tall.
  - `table_id` string, nullable: Unique identifier for the associated table.
  - `view_id` string, nullable: Unique identifier for the associated view.
  - `error` boolean: Whether the widget has a configuration error.
  - `created_at` string, date-time, required: Timestamp when the widget was created.
  - `updated_at` string, date-time, required: Timestamp when the widget was last updated.

## Other responses

- `422`: Dashboard not found.
- `500`: Server error.

---

[API](https://skmtc.dev/nocodb/apis/nocodb-v3.md) - [All operations](https://skmtc.dev/nocodb/apis/nocodb-v3/llms.txt) - [OpenAPI document](https://skmtc.dev/nocodb/apis/nocodb-v3/revisions/62a735aaf849?raw)