# `CarbonPhoenix.CoreComponents` [🔗](https://github.com/nyannus/carbon_phoenix/blob/v0.1.1/lib/carbon_phoenix/core_components.ex#L1) Provides core UI components, built on the [Carbon Design System web components](https://web-components.carbondesignsystem.com/). The components in this module keep the usual Phoenix API (`flash/1`, `button/1`, `input/1`, `header/1`, `table/1`, `list/1`, `icon/1`) but render Carbon elements. They expose the most relevant Carbon options as regular assigns. Every one of them also accepts a `carbon` map. Its entries are rendered as extra attributes on the underlying Carbon element, which makes every option from the storybook reachable, e.g. `carbon={%{helper_text: "Hi"}}` (underscores in keys become the dashes of the web component attribute). For a one-to-one wrapper of *every* Carbon web component and *every* attribute, see `CarbonPhoenix.WebComponents` (``, ``, ...). References: * [Carbon web components](https://web-components.carbondesignsystem.com/) - the storybook with all components and their options. * [Carbon icons](https://carbondesignsystem.com/elements/icons/library/) - see `icon/1` for usage. * [Phoenix.Component](https://phoenix-live-view.hexdocs.pm/Phoenix.Component.html) - the component system used by Phoenix. Some components, such as `<.link>` and `<.form>`, are defined there. # `button` Renders a Carbon button with navigation support. ## Examples <.button>Send! <.button phx-click="go" kind="danger">Delete <.button navigate={~p"/"} kind="tertiary" size="sm">Home <.button kind="ghost" icon="add" icon_only tooltip_text="Add">Add ## Attributes * `kind` (`:string`) - the Carbon button kind, defaults to `primary`. Defaults to `nil`. Must be one of `nil`, `"primary"`, `"secondary"`, `"tertiary"`, `"ghost"`, `"danger"`, `"danger--primary"`, `"danger--tertiary"`, `"danger--ghost"`, `"danger-tertiary"`, or `"danger-ghost"`. * `variant` (`:string`) - alias of `kind`, kept for compatibility with generated Phoenix code. Defaults to `nil`. * `size` (`:string`) - Defaults to `nil`.Must be one of `nil`, `"xs"`, `"sm"`, `"md"`, `"lg"`, `"xl"`, or `"2xl"`. * `expressive` (`:boolean`) - use the expressive button style. Defaults to `false`. * `selected` (`:boolean`) - selected state of icon-only ghost buttons. Defaults to `false`. * `icon` (`:string`) - name of a Carbon icon, see `icon/1`. Defaults to `nil`. * `icon_only` (`:boolean`) - render only the icon, label becomes tooltip. Defaults to `false`. * `tooltip_text` (`:string`) - Defaults to `nil`. * `tooltip_position` (`:string`) - Defaults to `nil`.Must be one of `nil`, `"top"`, `"right"`, `"bottom"`, or `"left"`. * `tooltip_alignment` (`:string`) - Defaults to `nil`.Must be one of `nil`, `"start"`, `"center"`, or `"end"`. * `danger_description` (`:string`) - screen reader text for the danger kinds. Defaults to `nil`. * `carbon` (`:map`) - extra Carbon button options as a map, e.g. `%{option_name: value}`. Defaults to `%{}`. * `class` (`:any`) - Defaults to `nil`. * Global attributes are accepted. Supports all globals plus: `["href", "navigate", "patch", "method", "download", "name", "value", "disabled", "type", "form", "formaction", "formmethod", "formtarget", "target", "rel", "hreflang", "ping", "autofocus"]`. ## Slots * `inner_block` (required) # `flash` Renders flash notices as Carbon toast notifications. Place flashes inside a positioned container, see `your layout's flash group component`. ## Examples <.flash kind={:info} flash={@flash} /> <.flash kind={:success} timeout={5000} flash={@flash} /> <.flash id="welcome-back" kind={:info} phx-mounted={show("#welcome-back") |> JS.remove_attribute("hidden")} hidden > Welcome Back! ## Attributes * `id` (`:string`) - the optional id of flash container. * `flash` (`:map`) - the map of flash messages to display. Defaults to `%{}`. * `title` (`:string`) - Defaults to `nil`. * `kind` (`:atom`) - used for styling and flash lookup. Must be one of `:info`, `:error`, `:success`, `:warning`, `:"info-square"`, or `:"warning-alt"`. * `caption` (`:string`) - optional caption shown below the message. Defaults to `nil`. * `timeout` (`:integer`) - milliseconds until the toast closes itself. Defaults to `nil`. * `low_contrast` (`:boolean`) - use the low contrast toast variant. Defaults to `false`. * `hide_close_button` (`:boolean`) - hide the close button. Defaults to `false`. * `carbon` (`:map`) - extra Carbon toast notification options as a map, e.g. `%{option_name: value}`. Defaults to `%{}`. * Global attributes are accepted. the arbitrary HTML attributes to add to the flash container. ## Slots * `inner_block` - the optional inner block that renders the flash message. # `header` Renders a header with title. ## Attributes * `carbon` (`:map`) - extra Carbon heading options as a map, e.g. `%{option_name: value}`. Defaults to `%{}`. ## Slots * `inner_block` (required) * `subtitle` * `actions` # `hide` # `icon` Renders a [Carbon icon](https://carbondesignsystem.com/elements/icons/library/). Pass the icon name as shown in the library, e.g. `add`, `warning--filled` or `chevron--down`. Icons use `currentColor` and scale to any size. ## Examples <.icon name="add" /> <.icon name="renew" size={24} class="spin" /> <.icon name="close" label="Close dialog" /> ## Attributes * `name` (`:string`) (required) - the Carbon icon name. * `size` (`:any`) - width and height in pixels. Defaults to `16`. * `label` (`:string`) - accessible label; the icon is decorative without it. Defaults to `nil`. * `class` (`:any`) - Defaults to `nil`. * Global attributes are accepted. # `input` Renders an input with label and error messages. A `Phoenix.HTML.FormField` may be passed as argument, which is used to retrieve the input name, id, and values. Otherwise all attributes may be passed explicitly. ## Types Each type renders the matching Carbon form control: | type | Carbon element | | --- | --- | | `text`, `email`, `tel`, `url`, `color`, `month`, `week`, `datetime-local` | Text input | | `password` | Password input | | `number` | Number input | | `search` | Search | | `textarea` | Text area | | `select` | Select (multi select with `multiple`) | | `dropdown`, `combo-box`, `multi-select` | Dropdown, combo box, multi select | | `radio-group` | Radio button group | | `checkbox` | Checkbox, used exclusively for boolean values | | `toggle` | Toggle, boolean value | | `range` | Slider | | `date` | Date picker | | `time` | Time picker | | `file` | File uploader | | `hidden` | plain `` | For live file uploads, see `Phoenix.Component.live_file_input/1`. Options that are not available as assigns can be passed through the `carbon` map, e.g. `carbon={%{enable_counter: true, max_count: 100}}`. ## Examples ```heex <.input field={@form[:email]} type="email" helper_text="We never share it" /> <.input name="my-input" errors={["oh no!"]} /> <.input field={@form[:age]} type="number" carbon={%{"min" => 0, "max" => 120}} /> ``` ## Select, dropdown, combo-box, multi-select and radio-group These types need `options` and optionally a `value` to mark which option should be preselected. Options may be plain values, `{label, value}` tuples, or `{group_label, options}` for grouped selects. ```heex <.input field={@form[:user_type]} type="select" options={["Admin": "admin", "User": "user"]} /> <.input field={@form[:tags]} type="multi-select" options={@tags} /> ``` ## Attributes * `id` (`:any`) - Defaults to `nil`. * `name` (`:any`) * `label` (`:string`) - Defaults to `nil`. * `value` (`:any`) * `type` (`:string`) - Defaults to `"text"`. Must be one of `"checkbox"`, `"color"`, `"date"`, `"datetime-local"`, `"email"`, `"file"`, `"month"`, `"number"`, `"password"`, `"search"`, `"select"`, `"tel"`, `"text"`, `"textarea"`, `"time"`, `"url"`, `"week"`, `"hidden"`, `"range"`, `"toggle"`, `"dropdown"`, `"combo-box"`, `"multi-select"`, or `"radio-group"`. * `field` (`Phoenix.HTML.FormField`) - a form field struct retrieved from the form, for example: @form[:email]. * `errors` (`:list`) - Defaults to `[]`. * `checked` (`:boolean`) - the checked flag for checkbox and toggle inputs. * `prompt` (`:string`) - the prompt for select inputs. Defaults to `nil`. * `options` (`:list`) - the options for select, dropdown, combo-box, multi-select, radio-group. * `multiple` (`:boolean`) - the multiple flag for select inputs. Defaults to `false`. * `helper_text` (`:string`) - help text shown below the input. Defaults to `nil`. * `hide_label` (`:boolean`) - visually hide the label. Defaults to `false`. * `size` (`:string`) - the Carbon input size. Defaults to `nil`. Must be one of `nil`, `"sm"`, `"md"`, or `"lg"`. * `warn` (`:boolean`) - show the warning state. Defaults to `false`. * `warn_text` (`:string`) - text shown in the warning state. Defaults to `nil`. * `inline` (`:boolean`) - use the inline layout where supported. Defaults to `false`. * `class` (`:any`) - class added to the Carbon element. Defaults to `nil`. * `carbon` (`:map`) - extra options of the Carbon input, e.g. `%{enable_counter: true}`. Defaults to `%{}`. * Global attributes are accepted. Supports all globals plus: `["accept", "autocomplete", "capture", "cols", "disabled", "form", "list", "max", "maxlength", "min", "minlength", "multiple", "pattern", "placeholder", "readonly", "required", "rows", "size", "step"]`. # `list` Renders a data list as a Carbon structured list. ## Examples <.list> <:item title="Title">{@post.title} <:item title="Views">{@post.views} ## Attributes * `condensed` (`:boolean`) - use less vertical space. Defaults to `false`. * `flush` (`:boolean`) - remove horizontal padding. Defaults to `false`. * `carbon` (`:map`) - extra Carbon structured list options as a map, e.g. `%{option_name: value}`. Defaults to `%{}`. ## Slots * `item` (required) - Accepts attributes: * `title` (`:string`) (required) # `show` # `table` Renders a Carbon data table. ## Examples <.table id="users" rows={@users}> <:col :let={user} label="id">{user.id} <:col :let={user} label="username" sortable>{user.username} ## Attributes * `id` (`:string`) (required) * `rows` (`:list`) (required) * `row_id` (`:any`) - the function for generating the row id. Defaults to `nil`. * `row_click` (`:any`) - the function for handling phx-click on each row. Defaults to `nil`. * `row_item` (`:any`) - the function for mapping each row before calling the :col and :action slots. Defaults to `&Function.identity/1`. * `size` (`:string`) - Defaults to `nil`.Must be one of `nil`, `"xs"`, `"sm"`, `"md"`, `"lg"`, or `"xl"`. * `zebra` (`:boolean`) - use zebra striping. Defaults to `true`. * `selectable` (`:boolean`) - show row selection checkboxes. Defaults to `false`. * `expandable` (`:boolean`) - Defaults to `false`. * `sortable` (`:boolean`) - make all columns sortable. Defaults to `false`. * `with_header` (`:boolean`) - Defaults to `false`. * `use_static_width` (`:boolean`) - Defaults to `false`. * `carbon` (`:map`) - extra Carbon table options as a map, e.g. `%{option_name: value}`. Defaults to `%{}`. ## Slots * `col` (required) - Accepts attributes: * `label` (`:string`) * `sortable` (`:boolean`) * `action` - the slot for showing user actions in the last table column. # `translate_error` Translates an error message using gettext. # `translate_errors` Translates the errors for a field from a keyword list of errors. --- *Consult [api-reference.md](api-reference.md) for complete listing*