# `MaterialSymbols`
[🔗](https://github.com/waseigo/material_symbols/blob/v1.0.0/lib/material_symbols.ex#L1)

Phoenix components for Google [Material Symbols](https://fonts.google.com/icons).

Material Symbols come in three styles: `outlined` (the default), `rounded`,
and `sharp`. Every icon also has a filled variant. Only the `outlined` style
is compiled by default; see "Compile-time configuration" below.

## Usage

    <MaterialSymbols.home />
    <MaterialSymbols.home style="outlined" />
    <MaterialSymbols.home fill />
    <MaterialSymbols.home size={32} class="text-blue-600" />
    <MaterialSymbols.render name="home" style="outlined" />

`style` selects the icon style and must be one of the compiled styles. `fill`
selects the filled variant. The SVG uses `fill="currentColor"`, so set the
color with `class` or with the surrounding CSS. The `style` HTML attribute is
reserved for the icon style.

`fill` is a boolean, `size` is a positive integer, and `style` is a string.
Use `fill` and `size={32}`; string values such as `fill="true"` and
`size="32"` raise, and so does an atom style such as `style={:rounded}`.
Explicit `width`, `height`, or `viewBox` attributes override the generated
defaults.

Per-icon components pass arbitrary attributes to the `<svg>` element.
`render/1` and `icon/1` accept global attributes such as `aria-*`, `data-*`,
`id`, and `role`, plus `width`, `height`, `viewBox`, `xmlns`,
`preserveAspectRatio`, and `focusable`. The default size is 24 pixels;
`size` sets both `width` and `height`. The `viewBox` is the Material Symbols
960-unit grid.

Use `icon_names/0` to list every compiled icon and `search_icons/1` to filter
names. Each icon is a public component, but ExDoc does not list all generated
components; browse the upstream set at <https://fonts.google.com/icons> or
use `icon_names/0` to discover them. Icon names that start with a digit get
an `icon_` prefix in the generated component name, so `9k` is
`<MaterialSymbols.icon_9k />`. `icon/1` and `render/1` accept the upstream
name (`"9k"`), the component name (`"icon_9k"`), or the component atom
(`:icon_9k`).

For dynamic names, use `<MaterialSymbols.icon name={@icon} />` when the name
comes from controlled data; it raises on an unknown name. `render/1` is the
lenient variant and emits an HTML comment for an unknown name.

## Compile-time configuration

By default, all 3,945 icons are available and only the `outlined` style is
compiled. Include more styles:

    config :material_symbols, styles: [:outlined, :rounded, :sharp]

Compile only selected icons:

    config :material_symbols, icons: [:home, :menu, :settings]

`styles` defaults to `[:outlined]`; `:all` includes all three. `icons`
defaults to `:all`. Use the upstream icon name in `icons`; the digit-leading
icon `9k` is configured as `"9k"` even though its component is `icon_9k`.
Component names such as `:icon_9k` are also accepted. Unknown icon or style
names fail the build, and so does a selected icon that lacks a requested
style/fill variant. This is compile-time configuration: changing it
recompiles the dependency. If `outlined` is not configured, the first
configured style becomes the default.

## Attribution

Material Symbols are designed by Google and licensed under the Apache
License 2.0. This package is not affiliated with Google.

# `icon`

Renders an icon by name and raises when the name is unknown.

Use this for dynamic names from controlled data. `render/1` emits an HTML
comment for unknown names instead.

Accepts the same style, fill, size, class, and global attributes as the
per-icon components.

## Attributes

* `name` (`:any`) (required)
* `style` (`:string`) - Defaults to `"outlined"`. Must be one of `"outlined"`.
* `fill` (`:boolean`) - Defaults to `false`.
* `size` (`:integer`) - Defaults to `24`.
* `class` (`:string`) - Defaults to `nil`.
* Global attributes are accepted. Supports all globals plus: `["width", "height", "viewBox", "xmlns", "preserveAspectRatio", "focusable"]`.

# `icon_name`

```elixir
@spec icon_name(atom()) :: String.t()
```

Returns the upstream icon name for a generated component name.

# `icon_names`

```elixir
@spec icon_names() :: [atom()]
```

Returns every generated component name as an atom.

# `render`

Renders an icon by name.

Accepts the same style, fill, size, class, and global attributes as the
per-icon components. Unknown names render an HTML comment.

## Attributes

* `name` (`:any`) (required)
* `style` (`:string`) - Defaults to `"outlined"`. Must be one of `"outlined"`.
* `fill` (`:boolean`) - Defaults to `false`.
* `size` (`:integer`) - Defaults to `24`.
* `class` (`:string`) - Defaults to `nil`.
* Global attributes are accepted. Supports all globals plus: `["width", "height", "viewBox", "xmlns", "preserveAspectRatio", "focusable"]`.

# `search_icons`

```elixir
@spec search_icons(String.t()) :: [atom()]
```

Returns the generated component names that contain `term`, case-insensitively.